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.

1 files changed, 99 insertions, 4 deletions

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