forked from Imagelibrary/rtems
2008-02-28 Joel Sherrill <joel.sherrill@oarcorp.com>
* shell/.cvsignore, shell/Makefile.am, shell/memory.t, shell/preface.texi, shell/shell.texi: Added much information the Preface. Created initial version of Configuration and Intialization chapter. Links are now complete from start to end of manual. * shell/confinit.t: New file.
This commit is contained in:
Joel Sherrill
253
doc/shell/confinit.t
Normal file
253
doc/shell/confinit.t
Normal file
@@ -0,0 +1,253 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1988-2008.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
@c
|
||||
@c $Id$
|
||||
@c
|
||||
|
||||
@chapter Configuration and Initialization
|
||||
|
||||
@section Introduction
|
||||
|
||||
This chapter provides information on how the application
|
||||
configures and intializes the RTEMS shell.
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
@section Configuration
|
||||
|
||||
The command set available to the application is user configurable.
|
||||
It is configured using a mechanism similar to the @code{confdefs.h}
|
||||
mechanism used to specify application configuration.
|
||||
|
||||
In the simplest case, if the user wishes to configure a command
|
||||
set with all commands available that are neither filesystem
|
||||
management (e.g. mounting, formating, etc.) or network related,
|
||||
then the following is all that is required:
|
||||
|
||||
@smallexample
|
||||
#define CONFIGURE_SHELL_COMMANDS_INIT
|
||||
#define CONFIGURE_SHELL_COMMANDS_ALL
|
||||
|
||||
#include <rtems/shellconfig.h>
|
||||
@end smallexample
|
||||
|
||||
In a slightly more complex example, if the user wishes to include
|
||||
all networking commands as well as support for mounting MS-DOS and
|
||||
NFS filesystems, then the following is all that is required:
|
||||
|
||||
@smallexample
|
||||
#define CONFIGURE_SHELL_COMMANDS_INIT
|
||||
#define CONFIGURE_SHELL_COMMANDS_ALL
|
||||
#define CONFIGURE_SHELL_MOUNT_MSDOS
|
||||
#define CONFIGURE_SHELL_MOUNT_NFS
|
||||
|
||||
#include <rtems/shellconfig.h>
|
||||
@end smallexample
|
||||
|
||||
@subsection Customizing the Command Set
|
||||
|
||||
The user can configure specific command sets by either building
|
||||
up the set from individual commands or starting with a complete
|
||||
set and disabling individual commands. Each command has two
|
||||
configuration macros associated with it.
|
||||
|
||||
@table @b
|
||||
|
||||
@item @code{CONFIGURE_SHELL_COMMAND_XXX}
|
||||
Each command has a constant of this form which is defined when
|
||||
building a command set by individually enabling specific
|
||||
commands.
|
||||
|
||||
@item @code{CONFIGURE_SHELL_NO_COMMAND_XXX}
|
||||
In contrast, each command has a similar command which is
|
||||
defined when the application is configuring a command set
|
||||
by disabling specific commands in the set.
|
||||
|
||||
@end table
|
||||
|
||||
@subsection 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:
|
||||
|
||||
@itemize @bullet
|
||||
|
||||
@item Provide a @i{main-style} function which implements
|
||||
the command. If that command function uses a @code{getopt}
|
||||
related function to parse arguments, it @b{MUST} use the
|
||||
reentrant form.
|
||||
|
||||
@item Provide a command definition structure of type
|
||||
@code{rtems_shell_cmd_t}.
|
||||
|
||||
@item Configure that command using the
|
||||
@code{CONFIGURE_SHELL_USER_COMMANDS} macro.
|
||||
@end itemize
|
||||
|
||||
Custom aliases are configured similarly but the user
|
||||
only provides an alias definition structure of type
|
||||
@code{rtems_shell_alias_t} and configures the alias
|
||||
via the @code{CONFIGURE_SHELL_USER_ALIASES} macro.
|
||||
|
||||
In the following example, we have implemented a custom
|
||||
command named @code{usercmd} which simply prints the
|
||||
arguments it was passed. We have also provided an
|
||||
alias for @code{usercmd} named @code{userecho}.
|
||||
|
||||
@smallexample
|
||||
#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>
|
||||
@end smallexample
|
||||
|
||||
Notice in the above example, that the user wrote the
|
||||
@i{main} for their command (e.g. @code{main_usercmd})
|
||||
which looks much like any other @code{main()}. They
|
||||
then defined a @code{rtems_shell_cmd_t} structure
|
||||
named @code{Shell_USERCMD_Command} which describes that
|
||||
command. This command definition structure is registered
|
||||
into the static command set by defining
|
||||
@code{CONFIGURE_SHELL_USER_COMMANDS} to
|
||||
@code{&Shell_USERCMD_Command}.
|
||||
|
||||
Similarly, to add the @code{userecho} alias, the user
|
||||
provides the alias definition structure named
|
||||
@code{Shell_USERECHO_Alias} and defines
|
||||
@code{CONFIGURE_SHELL_USER_ALIASES} to configure
|
||||
the alias.
|
||||
|
||||
The user can configure any number of commands
|
||||
and aliases in this manner.
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
@section Initialization
|
||||
|
||||
The shell may be easily attached to a serial port or
|
||||
to the @code{telnetd} server. This section describes
|
||||
how that is accomplished.
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
@subsection Attached to a Serial Port
|
||||
|
||||
Starting the shell attached to the console or a serial
|
||||
port is very simple. The user invokes @code{rtems_shell_init}
|
||||
with parameters to indicate the characteristics of the task
|
||||
that will be executing the shell including name, stack size,
|
||||
and priority. The user also specifies the device that the
|
||||
shell is to be attached to.
|
||||
|
||||
This example is taken from the @code{fileio} sample test.
|
||||
This shell portion of this test can be run on any target which
|
||||
provides a console with input and output capabilities. It does
|
||||
not include any commands which cannot be supported on all BSPs.
|
||||
The source code for this test is in @code{testsuites/samples/fileio}
|
||||
with the shell configuration in the @code{init.c} file.
|
||||
|
||||
@smallexample
|
||||
#include <rtems/shell.h>
|
||||
|
||||
void start_shell(void)
|
||||
@{
|
||||
printf(" =========================\n");
|
||||
printf(" starting shell\n");
|
||||
printf(" =========================\n");
|
||||
rtems_shell_init(
|
||||
"SHLL", /* task name */
|
||||
RTEMS_MINIMUM_STACK_SIZE * 4, /* task stack size */
|
||||
100, /* task priority */
|
||||
"/dev/console", /* device name */
|
||||
0, /* initial termios cflag value */
|
||||
0 /* run forever */
|
||||
);
|
||||
rtems_task_suspend(RTEMS_SELF);
|
||||
@}
|
||||
@end smallexample
|
||||
|
||||
In the above example, the call to @code{rtems_shell_init}
|
||||
spawns a task to run the RTEMS Shell attached to @code{/dev/console}
|
||||
and executing at priority 100. The caller suspends itself and
|
||||
lets the shell take over the console device.
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
@subsection Attached to a Socket
|
||||
|
||||
TBD
|
||||
|
||||
@section Functions
|
||||
|
||||
This section describes the Shell related C functions which are
|
||||
publicly available related to initialization and configuration.
|
||||
|
||||
@page
|
||||
@subsection rtems_shell_init - initialize the shell
|
||||
|
||||
@cindex initialization
|
||||
|
||||
@subheading CALLING SEQUENCE:
|
||||
|
||||
@findex rtems_shell_init
|
||||
@example
|
||||
rtems_status_code rtems_shell_init (
|
||||
char *task_name,
|
||||
uint32_t task_stacksize,
|
||||
rtems_task_priority task_priority,
|
||||
char *devname,
|
||||
tcflag_t tcflag,
|
||||
int forever
|
||||
);
|
||||
@end example
|
||||
|
||||
@subheading DIRECTIVE STATUS CODES:
|
||||
@code{RTEMS_SUCCESSFUL} - Shell task spawned successfully@*
|
||||
others - to indicate a failure condition
|
||||
|
||||
@subheading DESCRIPTION:
|
||||
This service creates a task with the specified characteristics to
|
||||
run the RTEMS Shell attached to the specified @code{devname}.
|
||||
|
||||
@subheading NOTES:
|
||||
|
||||
This method invokes the @code{rtems_task_create} and @code{rtems_task_start}
|
||||
directives and as such may return any status code that those directives
|
||||
may return.
|
||||
|
||||
Reference in New Issue
Block a user