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.

7 files changed, 382 insertions, 17 deletions

diff --git a/doc/ChangeLog b/doc/ChangeLog
index 233bf4f19f..4189e2cd37 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,5 +1,13 @@
 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.
+
+2008-02-28	Joel Sherrill <joel.sherrill@oarcorp.com>
+
 	* shell/file.t, shell/network.t: Document more commands and provide
 	more examples.
 
diff --git a/doc/shell/.cvsignore b/doc/shell/.cvsignore
index f408039f93..1eaad1cf42 100644
--- a/doc/shell/.cvsignore
+++ b/doc/shell/.cvsignore
@@ -1,3 +1,4 @@
+confinit.texi
 file.texi
 general.texi
 index.html
diff --git a/doc/shell/Makefile.am b/doc/shell/Makefile.am
index 506fd6b4e5..8e13f23383 100644
--- a/doc/shell/Makefile.am
+++ b/doc/shell/Makefile.am
@@ -14,37 +14,43 @@ include $(top_srcdir)/main.am
 
 FILES = shell.texi preface.texi
 
-GENERATED_FILES = general.texi file.texi memory.texi rtems.texi network.texi
+GENERATED_FILES = confinit.texi general.texi file.texi memory.texi \
+    rtems.texi network.texi
 
 COMMON_FILES += $(top_srcdir)/common/cpright.texi
 
 info_TEXINFOS = shell.texi
 shell_TEXINFOS = $(FILES) $(COMMON_FILES) $(GENERATED_FILES)
 
-general.texi: general.t
+confinit.texi: confinit.t
 	$(BMENU2) -p "Preface" \
 	    -u "Top" \
-	    -n "" < $< > $@
+	    -n "General Commands" < $< > $@
+
+general.texi: general.t
+	$(BMENU2) -p "Configuration and Initialization rtems_shell_init - initialize the shell" \
+	    -u "Top" \
+	    -n "File and Directory Commands" < $< > $@
 
 file.texi: file.t
-	$(BMENU2) -p "" \
+	$(BMENU2) -p "General Commands exit - exit the shell" \
 	    -u "Top" \
-	    -n "" < $< > $@
+	    -n "Memory Commands" < $< > $@
 
 memory.texi: memory.t
-	$(BMENU2) -p "" \
+	$(BMENU2) -p "File and Directory Commands cd - alias for chdir" \
 	    -u "Top" \
-	    -n "" < $< > $@
+	    -n "RTEMS Specific Commands" < $< > $@
 
 rtems.texi: rtems.t
-	$(BMENU2) -p "" \
+	$(BMENU2) -p "Memory Commands malloc - obtain information on C program heap" \
 	    -u "Top" \
-	    -n "" < $< > $@
+	    -n "Network Commands" < $< > $@
 
 network.texi: network.t
-	$(BMENU2) -p "" \
+	$(BMENU2) -p "RTEMS Specific Commands dname - displays information about named drivers" \
 	    -u "Top" \
-	    -n "" < $< > $@
+	    -n "Function and Variable Index" < $< > $@
 
 EXTRA_DIST = general.t file.t memory.t rtems.t network.t
 
diff --git a/doc/shell/confinit.t b/doc/shell/confinit.t
new file mode 100644
index 0000000000..bb94b608a3
--- /dev/null
+++ b/doc/shell/confinit.t
@@ -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.
+
diff --git a/doc/shell/memory.t b/doc/shell/memory.t
index c18e462c72..cb78277b20 100644
--- a/doc/shell/memory.t
+++ b/doc/shell/memory.t
@@ -438,7 +438,7 @@ extern rtems_shell_cmd_t rtems_shell_MMOVE_Command;
 @c
 @c
 @page
-@subsection malloc - obtain information on c program heap
+@subsection malloc - obtain information on C program heap
 
 @pgindex malloc
 
diff --git a/doc/shell/preface.texi b/doc/shell/preface.texi
index c3dfafc299..5868a10201 100644
--- a/doc/shell/preface.texi
+++ b/doc/shell/preface.texi
@@ -7,11 +7,106 @@
 @c
 
 @ifinfo
-@node Preface, General Commands, Top, Top
+@node Preface, Configuration and Initialization, Top, Top
 @end ifinfo
 @unnumbered Preface
 
 Real-time embedded systems vary widely based upon their 
-operational and maintenance requirements. Many of these
-systems now include a command line interface which can
-be used to diagnostic 
+operational and maintenance requirements. Some of these
+systems provide ways for the user or developer to interact
+with them.  This interaction could be used for operational,
+diagnostic, or configuration purposes.  The capabilities
+described in this manual are those provided with RTEMS to
+provide a command line interface for user access.  Some
+of these commands will be familiar as standard POSIX utilities
+while others are RTEMS specific or helpful in debugging
+and analyzing an embedded system. As a simple example of
+the powerful and very familiar capabilities that the RTEMS
+Shell provides to an application, consider the following 
+example which hints at some of the capabilities available:
+
+@smallexample
+Welcome to rtems-4.8.99.0(SPARC/w/FPU/sis)
+COPYRIGHT (c) 1989-2008.
+On-Line Applications Research Corporation (OAR).
+
+Login into RTEMS
+
+login: rtems
+Password: 
+
+RTEMS SHELL (Ver.1.0-FRC):/dev/console. Feb 28 2008. 'help' to list commands.
+SHLL [/] $ cat /etc/passwd
+root:*:0:0:root::/:/bin/sh
+rtems:*:1:1:RTEMS Application::/:/bin/sh
+tty:!:2:2:tty owner::/:/bin/false
+SHLL [/] $ ls /dev
+-rwxr-xr-x   1  rtems   root           0 Jan 01 00:00 console 
+-rwxr-xr-x   1   root   root           0 Jan 01 00:00 console_b 
+2 files 0 bytes occupied
+SHLL [/] $ stackuse
+Stack usage by thread
+    ID      NAME    LOW          HIGH     CURRENT     AVAILABLE     USED
+0x09010001  IDLE 0x023d89a0 - 0x023d99af 0x023d9760      4096        608
+0x0a010001  UI1  0x023d9f30 - 0x023daf3f 0x023dad18      4096       1804
+0x0a010002  SHLL 0x023db4c0 - 0x023df4cf 0x023de9d0     16384       6204
+0xffffffff  INTR 0x023d2760 - 0x023d375f 0x00000000      4080        316
+SHLL [/] $ mount -L
+File systems: msdos 
+SHLL [/] $ 
+@end smallexample
+
+In the above example, the user @i{rtems} logs into a
+SPARC based RTEMS system.  The first command is 
+@code{cat /etc/passwd}.  This simple command lets us
+know that this application is running the In Memory
+File System (IMFS) and that the infrastructure has 
+provided dummy entries for @i{/etc/passwd} and a few
+other files.  The contents of @i{/etc/passwd} let
+us know that the user could have logged in as @code{root}.
+In fact, the @code{root} user has more permissions
+than @code{rtems} who is not allowed to write into the
+filesystem.  
+
+The second command is @code{ls /dev} which lets us
+know that RTEMS has POSIX-style device nodes which
+can be accesses through standard I/O function calls.
+
+The third command executed is the RTEMS specific 
+@code{stackuse} which gives a report on the stack
+usage of each thread in the system.  Since stack
+overflows are a common error in deeply embedded systems,
+this is a surprising simple, yet powerful debugging aid.
+
+Finally, the last command, @code{mount -L} hints that
+RTEMS supports a variety of mountable filesystems. With
+support for MS-DOS FAT on IDE/ATA and Flash devices as
+well as network-based filesystens such as NFS and TFTP,
+the standard free RTEMS provides a robuse infrastructure
+for embedded applications.
+
+This manual describes the RTEMS Shell and its command set. 
+In our terminology, the Shell is just a loop reading user
+input and turning that input into commands with argument.
+The Shell provided with RTEMS is a simple command reading
+loop with limited scripting capabilities.  It can be connected
+to via a standard serial port or connected to the RTEMS
+@code{telnetd} server for use across a network.
+
+Each command in the command set is implemented as a single
+subroutine which has a @i{main-style} prototype.  The commands
+interpret their arguments and operate upon stdin, stdout, and
+stderr by default.  This allows each command to be invoked
+independent of the shell.
+
+The described separation of shell from commands from communications
+mechanism was an important design goal.  At one level, the RTEMS
+Shell is a complete shell environment providing access to multiple
+POSIX compliant filesystems and TCP/IP stack.  The subset of
+capabilities available is easy to configure and the standard
+Shell can be logged into from either a serial port or via telnet.
+But at another level, the Shell is a large set of components which
+can be integrated into the user's developed command interpreter.
+In either case, it is trivial to add custom commands to the command
+set available.
+ 
diff --git a/doc/shell/shell.texi b/doc/shell/shell.texi
index 5a44678d36..085283c7e8 100644
--- a/doc/shell/shell.texi
+++ b/doc/shell/shell.texi
@@ -66,6 +66,7 @@
 @contents
 
 @include preface.texi
+@include confinit.texi
 @include general.texi
 @include file.texi
 @include memory.texi
@@ -79,6 +80,7 @@ This is the online version of the RTEMS Shell User's Guide.
 
 @menu
 * Preface::
+* Configuration and Initialization::
 * General Commands::
 * File and Directory Commands::
 * Memory Commands::
@@ -95,7 +97,7 @@ This is the online version of the RTEMS Shell User's Guide.
 @c Need to copy the emacs stuff and "trailer stuff" (index, toc) into here
 @c
 
-@node Function and Variable Index, Concept Index, , Top
+@node Function and Variable Index, Concept Index, Network Commands route - show or manipulate the ip routing table, Top
 @unnumbered Function and Variable Index
 @printindex fn