2008-02-27 Joel Sherrill <joel.sherrill@oarcorp.com>

	* shell/file.t, shell/general.t, shell/memory.t, shell/network.t,
	shell/rtems.t, shell/shell.texi: Many commands now have real
	descriptions with examples.

6 files changed, 488 insertions, 158 deletions

diff --git a/doc/shell/file.t b/doc/shell/file.t
index 28cf967afa..f4673c8bce 100644
--- a/doc/shell/file.t
+++ b/doc/shell/file.t
@@ -36,6 +36,11 @@ The RTEMS shell has the following file and directory commands:
 
 @section Commands
 
+This section details the File and Directory Commands available.  A
+subsection is dedicated to each of the commands and
+describes the behavior and configuration of that
+command as well as providing an example usage.
+
 @c
 @c
 @c
diff --git a/doc/shell/general.t b/doc/shell/general.t
index 48fed6af0e..5b8eac7b5f 100644
--- a/doc/shell/general.t
+++ b/doc/shell/general.t
@@ -15,10 +15,10 @@ The RTEMS shell has the following general commands:
 @itemize @bullet
 
 @item @code{alias} - Add alias for an existing command
-@item @code{date} - Print current date and time
+@item @code{date} - Print or set current date and time
 @item @code{id} - show uid gid euid and egid
 @item @code{tty} - show ttyname
-@item @code{whoami} - show current user
+@item @code{whoami} - print effective user id
 @item @code{logoff} - logoff from the system
 @item @code{exit} - alias for logoff command
 
@@ -26,6 +26,10 @@ The RTEMS shell has the following general commands:
 
 @section Commands
 
+This section details the General Commands available.  A
+subsection is dedicated to each of the commands and
+describes the behavior and configuration of that
+command as well as providing an example usage.
 @c
 @c
 @c
@@ -106,7 +110,7 @@ extern rtems_shell_cmd_t rtems_shell_ALIAS_Command;
 @c
 @c
 @page
-@subsection date - print current date and time
+@subsection date - print or set current date and time
 
 @pgindex date
 
@@ -114,11 +118,18 @@ extern rtems_shell_cmd_t rtems_shell_ALIAS_Command;
 
 @example
 date
+date DATE TIME
 @end example
 
 @subheading DESCRIPTION:
 
-This command prints the current date.
+This command operates one of two modes.  When invoked with no
+arguments, it prints the current date and time.  When invoked
+with both @code{date} and @code{time} arguments, it sets the
+current time.  
+
+The @code{date} is specified in @code{YYYY-MM-DD} format.
+The @code{time} is specified in @code{HH:MM:SS} format.
 
 @subheading EXIT STATUS:
 
@@ -134,7 +145,10 @@ The following is an example of how to use @code{date}:
 
 @example
 SHLL [/] $ date
-Fri Jan  1 00:00:06 1988
+Fri Jan  1 00:00:09 1988
+SHLL [/] $ date 2008-02-29 06:45:32
+SHLL [/] $ date
+Fri Feb 29 06:45:35 2008
 @end example
 
 @subheading CONFIGURATION:
@@ -188,7 +202,9 @@ id
 
 @subheading DESCRIPTION:
 
-This command XXX
+This command prints the user identity.  This includes the user id
+(uid), group id (gid), effective user id (euid), and effective
+group id (egid).
 
 @subheading EXIT STATUS:
 
@@ -196,14 +212,26 @@ This command returns 0 on success and non-zero if an error is encountered.
 
 @subheading NOTES:
 
-NONE
+Remember there is only one POSIX process in a single processor RTEMS
+application. Each thread may have its own user identity and that
+identity is used by the filesystem to enforce permissions.
 
 @subheading EXAMPLES:
 
-The following is an example of how to use @code{id}:
+The first example of the @code{id} command is from a session logged
+in as the normal user @code{rtems}:
 
 @example
-EXAMPLE_TBD
+SHLL [/] # id
+uid=1(rtems),gid=1(rtems),euid=1(rtems),egid=1(rtems)
+@end example
+
+The second example of the @code{id} command is from a session logged
+in as the @code{root} user:
+
+@example
+SHLL [/] # id
+uid=0(root),gid=0(root),euid=0(root),egid=0(root)
 @end example
 
 @subheading CONFIGURATION:
@@ -257,7 +285,8 @@ tty
 
 @subheading DESCRIPTION:
 
-This command XXX
+This command prints the file name of the device connected
+to standard input.
 
 @subheading EXIT STATUS:
 
@@ -272,7 +301,8 @@ NONE
 The following is an example of how to use @code{tty}:
 
 @example
-EXAMPLE_TBD
+SHLL [/] $ tty
+/dev/console
 @end example
 
 @subheading CONFIGURATION:
@@ -314,7 +344,7 @@ extern rtems_shell_cmd_t rtems_shell_TTY_Command;
 @c
 @c
 @page
-@subsection whoami - show current user
+@subsection whoami - print effective user id
 
 @pgindex whoami
 
@@ -326,11 +356,12 @@ whoami
 
 @subheading DESCRIPTION:
 
-This command XXX
+This command displays the user name associated with the current
+effective user id.
 
 @subheading EXIT STATUS:
 
-This command returns 0 on success and non-zero if an error is encountered.
+This command always succeeds.
 
 @subheading NOTES:
 
@@ -341,7 +372,8 @@ NONE
 The following is an example of how to use @code{whoami}:
 
 @example
-EXAMPLE_TBD
+SHLL [/] $ whoami
+rtems
 @end example
 
 @subheading CONFIGURATION:
@@ -395,22 +427,26 @@ logoff
 
 @subheading DESCRIPTION:
 
-This command XXX
+This command logs the user out of the shell.
 
 @subheading EXIT STATUS:
 
-This command returns 0 on success and non-zero if an error is encountered.
+This command does not return.
 
 @subheading NOTES:
 
-NONE
+The system behavior when the shell is exited depends upon how the
+shell was initiated.  The typical behavior is that a login prompt
+will be displayed for the next login attempt or that the connection
+will be dropped by the RTEMS system.
 
 @subheading EXAMPLES:
 
 The following is an example of how to use @code{logoff}:
 
 @example
-EXAMPLE_TBD
+SHLL [/] $ logoff
+logoff from the system...
 @end example
 
 @subheading CONFIGURATION:
@@ -452,7 +488,7 @@ extern rtems_shell_cmd_t rtems_shell_LOGOFF_Command;
 @c
 @c
 @page
-@subsection exit - alias for logoff command
+@subsection exit - exit the shell
 
 @pgindex exit
 
@@ -464,56 +500,32 @@ exit
 
 @subheading DESCRIPTION:
 
-This command XXX
+This command causes the shell interpreter to @code{exit}.
 
 @subheading EXIT STATUS:
 
-This command returns 0 on success and non-zero if an error is encountered.
+This command does not return.
 
 @subheading NOTES:
 
-NONE
+In contrast to @ref{General Commands logoff - logoff from the system, logoff},
+this command is built into the shell interpreter loop.
 
 @subheading EXAMPLES:
 
 The following is an example of how to use @code{exit}:
 
 @example
-EXAMPLE_TBD
+SHLL [/] $ exit
+Shell exiting
 @end example
 
 @subheading CONFIGURATION:
 
-@findex CONFIGURE_SHELL_NO_COMMAND_EXIT
-@findex CONFIGURE_SHELL_COMMAND_EXIT
-
-This command is included in the default shell command set.  
-When building a custom command set, define
-@code{CONFIGURE_SHELL_COMMAND_EXIT} to have this
-command included.
-
-This command can be excluded from the shell command set by
-defining @code{CONFIGURE_SHELL_NO_COMMAND_EXIT} when all
-shell commands have been configured.
+This command is always present and cannot be disabled.
 
 @subheading PROGRAMMING INFORMATION:
 
-@findex rtems_shell_rtems_main_exit
-
-The @code{exit} is implemented by a C language function
-which has the following prototype:
-
-@example
-int rtems_shell_rtems_main_exit(
-  int    argc,
-  char **argv
-);
-@end example
-
-The configuration structure for the @code{exit} has the
-following prototype:
-
-@example
-extern rtems_shell_cmd_t rtems_shell_EXIT_Command;
-@end example
+The @code{exit} is implemented directly in the shell interpreter.
+There is no C routine associated with it.
 
diff --git a/doc/shell/memory.t b/doc/shell/memory.t
index 05e630de0a..c18e462c72 100644
--- a/doc/shell/memory.t
+++ b/doc/shell/memory.t
@@ -25,6 +25,11 @@ The RTEMS shell has the following memory commands:
 
 @section Commands
 
+This section details the Memory Commands available.  A
+subsection is dedicated to each of the commands and
+describes the behavior and configuration of that
+command as well as providing an example usage.
+
 @c
 @c
 @c
@@ -36,28 +41,43 @@ The RTEMS shell has the following memory commands:
 @subheading SYNOPSYS:
 
 @example
-mdump [addr [size]]
+mdump [address [length]]
 @end example
 
 @subheading DESCRIPTION:
 
-This command XXX
+This command displays the contents of memory at the @code{address}
+and @code{length} in bytes specified on the command line.  
+
+When @code{length} is not provided, it defaults to @code{320} which
+is twenty lines of output with sixteen bytes of output per line.
+
+When @code{address} is not provided, it defaults to @code{0x00000000}.
 
 @subheading EXIT STATUS:
 
-This command returns 0 on success and non-zero if an error is encountered.
+This command always returns 0 to indicate success.
 
 @subheading NOTES:
 
-NONE
+Dumping memory from a non-existent address may result in an unrecoverable
+program fault.
 
 @subheading EXAMPLES:
 
 The following is an example of how to use @code{mdump}:
 
-@example
-EXAMPLE_TBD
-@end example
+@smallexample
+SHLL [/] $ mdump 0x10000 32
+0x0001000000 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00 ................
+0x0001001000 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00 ................
+SHLL [/] $ mdump 0x02000000 32
+0x02000000A1 48 00 00 29 00 80 33-81 C5 22 BC A6 10 21 00 .H..)..3.."...!.
+0x02000010A1 48 00 00 29 00 80 33-81 C5 22 BC A6 10 21 01 .H..)..3.."...!.
+SHLL [/] $ mdump 0x02001000 32
+0x0200100003 00 80 00 82 10 60 00-81 98 40 00 83 48 00 00 ......`...@..H..
+0x0200101084 00 60 01 84 08 A0 07-86 10 20 01 87 28 C0 02 ..`....... ..(..
+@end smallexample
 
 @subheading CONFIGURATION:
 
@@ -105,28 +125,37 @@ extern rtems_shell_cmd_t rtems_shell_MDUMP_Command;
 @subheading SYNOPSYS:
 
 @example
-wdump [addr [size]]
+wdump [address [length]]
 @end example
 
 @subheading DESCRIPTION:
 
-This command XXX
+This command displays the contents of memory at the @code{address}
+and @code{length} in bytes specified on the command line.  
+
+When @code{length} is not provided, it defaults to @code{320} which
+is twenty lines of output with sixteen bytes of output per line.
+
+When @code{address} is not provided, it defaults to @code{0x00000000}.
 
 @subheading EXIT STATUS:
 
-This command returns 0 on success and non-zero if an error is encountered.
+This command always returns 0 to indicate success.
 
 @subheading NOTES:
 
-NONE
+Dumping memory from a non-existent address may result in an unrecoverable
+program fault.
 
 @subheading EXAMPLES:
 
 The following is an example of how to use @code{wdump}:
 
-@example
-EXAMPLE_TBD
-@end example
+@smallexample
+SHLL [/] $ wdump 0x02010000 32
+0x02010000 0201 08D8 0201 08C0-0201 08AC 0201 0874 ...............t
+0x02010010 0201 0894 0201 0718-0201 0640 0201 0798 ...........@....
+@end smallexample
 
 @subheading CONFIGURATION:
 
@@ -174,12 +203,14 @@ extern rtems_shell_cmd_t rtems_shell_WDUMP_Command;
 @subheading SYNOPSYS:
 
 @example
-medit addr value [value ...]
+medit address value1 [value2 ... valueN]
 @end example
 
 @subheading DESCRIPTION:
 
-This command XXX
+This command is used to modify the contents of the memory starting
+at @code{address} using the octets specified by the parameters
+@code{value1} through @code{valueN}.
 
 @subheading EXIT STATUS:
 
@@ -187,15 +218,22 @@ This command returns 0 on success and non-zero if an error is encountered.
 
 @subheading NOTES:
 
-NONE
+Dumping memory from a non-existent address may result in an unrecoverable
+program fault.
 
 @subheading EXAMPLES:
 
 The following is an example of how to use @code{medit}:
 
-@example
-EXAMPLE_TBD
-@end example
+@smallexample
+SHLL [/] $ mdump 0x02000000 32
+0x02000000 A1 48 00 00 29 00 80 33-81 C5 22 BC A6 10 21 00 .H..)..3.."...!.
+0x02000010 A1 48 00 00 29 00 80 33-81 C5 22 BC A6 10 21 01 .H..)..3.."...!.
+SHLL [/] $  medit 0x02000000 0x01 0x02 0x03 0x04 0x05 0x06 0x07 0x08 0x09
+SHLL [/] $ mdump 0x02000000 32
+0x02000000 01 02 03 04 05 06 07 08-09 00 22 BC A6 10 21 00 .........."...!.
+0x02000010 A1 48 00 00 29 00 80 33-81 C5 22 BC A6 10 21 01 .H..)..3.."...!.
+@end smallexample
 
 @subheading CONFIGURATION:
 
@@ -243,12 +281,14 @@ extern rtems_shell_cmd_t rtems_shell_MEDIT_Command;
 @subheading SYNOPSYS:
 
 @example
-mfill addr size value
+mfill address length value
 @end example
 
 @subheading DESCRIPTION:
 
-This command XXX
+This command is used to fill the memory starting at @code{address}
+for the specified @code{length} in octets when the specified at
+@code{value}.
 
 @subheading EXIT STATUS:
 
@@ -256,15 +296,31 @@ This command returns 0 on success and non-zero if an error is encountered.
 
 @subheading NOTES:
 
-NONE
+Filling a non-existent address range may result in an unrecoverable
+program fault.  Similarly overwriting interrupt vector tables, code
+space or critical data areas can be fatal as shown in the example.
 
 @subheading EXAMPLES:
 
-The following is an example of how to use @code{mfill}:
-
-@example
-EXAMPLE_TBD
-@end example
+In this example, the address used (@code{0x23d89a0}) as the base
+address of the filled area is the end of the stack for the 
+Idle thread.  This address was determined manually using gdb and
+is very specific to this application and BSP.  The first command
+in this example is an @code{mdump} to display the initial contents
+of this memory.  We see that the first 8 bytes are 0xA5 which is
+the pattern used as a guard by the Stack Checker.  On
+the first context switch after the pattern is overwritten
+by the  @code{mfill} command, the Stack Checker detect the pattern
+has been corrupted and generates a fatal error.
+
+@smallexample
+SHLL [/] $ mdump 0x23d89a0 16
+0x023D89A0 A5 A5 A5 A5 A5 A5 A5 A5-FE ED F0 0D 0B AD 0D 06 ................
+SHLL [/] $ mfill 0x23d89a0 13 0x5a
+SHLL [/] $ BLOWN STACK!!! Offending task(0x23D4418): id=0x09010001; name=0x0203D908
+  stack covers range 0x23D89A0 - 0x23D99AF (4112 bytes)
+  Damaged pattern begins at 0x023D89A8 and is 16 bytes long
+@end smallexample
 
 @subheading CONFIGURATION:
 
@@ -312,12 +368,14 @@ extern rtems_shell_cmd_t rtems_shell_MFILL_Command;
 @subheading SYNOPSYS:
 
 @example
-mmove dst src size
+mmove dst src length
 @end example
 
 @subheading DESCRIPTION:
 
-This command XXX
+This command is used to copy the contents of the memory
+starting at @code{src} to the memory located at @code{dst}
+for the specified @code{length} in octets.
 
 @subheading EXIT STATUS:
 
@@ -331,9 +389,15 @@ NONE
 
 The following is an example of how to use @code{mmove}:
 
-@example
-EXAMPLE_TBD
-@end example
+@smallexample
+SHLL [/] $ mdump 0x023d99a0 16
+0x023D99A0 A5 A5 A5 A5 A5 A5 A5 A5-A5 A5 A5 A5 A5 A5 A5 A5 ................
+SHLL [/] $ mdump 0x02000000 16
+0x02000000 A1 48 00 00 29 00 80 33-81 C5 22 BC A6 10 21 00 .H..)..3.."...!.
+SHLL [/] $ mmove 0x023d99a0 0x02000000 13
+SHLL [/] $ mdump 0x023d99a0 16
+0x023D99A0 A1 48 00 00 29 00 80 33-81 C5 22 BC A6 A5 A5 A5 .H..)..3..".....
+@end smallexample
 
 @subheading CONFIGURATION:
 
@@ -386,7 +450,40 @@ malloc [info|stats]
 
 @subheading DESCRIPTION:
 
-This command XXX
+This command prints either information or statistics about the
+C Program Heap used by the @code{malloc} family of calls based upon
+the value of the first argument passed to the command.
+
+When the subcommand @code{info} is specified, information on the
+current state of the C Program Heap is reported.  This includes the following
+information:
+
+@itemize @bullet
+@item Number of free blocks
+@item Largest free block
+@item Total bytes free
+@item Number of used blocks
+@item Largest used block
+@item Total bytes used
+@end itemize
+
+When the subcommand @code{stats} is specified, statistics on the
+the C Program Heap are reported.  Malloc Family Statistics must
+be enabled for all of the values to be updated.  The statistics
+available includes the following information:
+
+@itemize @bullet
+@item 
+@item Currently available memory (in kilobytes)
+@item Currently allocated memory (in kilobytes)
+@item Maximum amount of memory ever allocated (in kilobytes)
+@item Lifetime tally of allocated memory  (in kilobytes)
+@item Lifetime tally of freed memory (in kilobytes)
+@item Number of calls to @code{malloc}
+@item Number of calls to @code{free}
+@item Number of calls to @code{realloc}
+@item Number of calls to @code{calloc}
+@end itemize
 
 @subheading EXIT STATUS:
 
@@ -394,16 +491,47 @@ This command returns 0 on success and non-zero if an error is encountered.
 
 @subheading NOTES:
 
-NONE
+@findex CONFIGURE_MALLOC_STATISTICS
+
+The @code{CONFIGURE_MALLOC_STATISTICS} @code{confdefs.h} constant
+must be defined when the application is configured for the full
+set of statistics information to be available.
 
 @subheading EXAMPLES:
 
-The following is an example of how to use @code{malloc}:
+The following is an example of how to use the @code{malloc} command.
 
 @example
-EXAMPLE_TBD
+SHLL [/] $ malloc info
+Number of free blocks: 3
+Largest free block:    3626672
+Total bytes free:      3627768
+Number of used blocks: 130
+Largest used block:    1048
+Total bytes used:      10136
+SHLL [/] $ malloc stats
+Malloc statistics
+  avail:3552k  allocated:9k (0%) max:10k (0%) lifetime:21k freed:12k
+  Call counts:   malloc:203   free:93   realloc:0   calloc:20
+SHLL [/] $ malloc info
+Number of free blocks: 3
+Largest free block:    3626672
+Total bytes free:      3627768
+Number of used blocks: 130
+Largest used block:    1048
+Total bytes used:      10136
+SHLL [/] $ malloc stats
+Malloc statistics
+  avail:3552k  allocated:9k (0%) max:10k (0%) lifetime:23k freed:14k
+  Call counts:   malloc:205   free:95   realloc:0   calloc:20
 @end example
 
+Note that in the above example, the lifetime allocated and free
+values have increased between the two calls to @code{malloc stats}
+even though the amount of memory available in the C Program Heap
+is the same in both the @code{malloc info} invocations. This indicates
+that memory was allocated and freed as a side-effect of the commands.
+
 @subheading CONFIGURATION:
 
 @findex CONFIGURE_SHELL_NO_COMMAND_MALLOC
diff --git a/doc/shell/network.t b/doc/shell/network.t
index c839c0c978..fab482d895 100644
--- a/doc/shell/network.t
+++ b/doc/shell/network.t
@@ -22,6 +22,10 @@ The RTEMS shell has the following network commands:
 
 @section Commands
 
+This section details the Network Commands available.  A
+subsection is dedicated to each of the commands and
+describes the behavior and configuration of that
+command as well as providing an example usage.
 @c
 @c
 @c
diff --git a/doc/shell/rtems.t b/doc/shell/rtems.t
index b502ce43c3..3e7e63d1f3 100644
--- a/doc/shell/rtems.t
+++ b/doc/shell/rtems.t
@@ -6,7 +6,7 @@
 @c  $Id$
 @c
 
-@chapter RTEMS Commands
+@chapter RTEMS Specific Commands
 
 @section Introduction
 
@@ -34,6 +34,10 @@ The RTEMS shell has the following rtems commands:
 
 @section Commands
 
+This section details the RTEMS Specific Commands available.  A
+subsection is dedicated to each of the commands and
+describes the behavior and configuration of that
+command as well as providing an example usage.
 @c
 @c
 @c
@@ -50,7 +54,10 @@ cpuuse [-r]
 
 @subheading DESCRIPTION:
 
-This command XXX
+This command may be used to print a report on the per thread
+cpu usage or to reset the per thread CPU usage statistics. When
+invoked with the @code{-r} option, the CPU usage statistics
+are reset.
 
 @subheading EXIT STATUS:
 
@@ -58,16 +65,45 @@ This command returns 0 on success and non-zero if an error is encountered.
 
 @subheading NOTES:
 
-NONE
+The granularity of the timing information reported is dependent
+upon the BSP and the manner in which RTEMS was built.  In the
+default RTEMS configuration, if the BSP supports nanosecond
+granularity timestamps, then the information reported will be
+highly accurate. Otherwise, the accuracy of the information
+reported is limited by the clock tick quantum.
 
 @subheading EXAMPLES:
 
 The following is an example of how to use @code{cpuuse}:
 
 @example
-EXAMPLE_TBD
+SHLL [/] $ cpuuse
+CPU Usage by thread
+   ID            NAME         SECONDS   PERCENT
+0x09010001   IDLE            49.745393   98.953
+0x0a010001   UI1              0.000000    0.000
+0x0a010002   SHLL             0.525928    1.046
+Time since last CPU Usage reset 50.271321 seconds
+SHLL [/] $ cpuuse -r
+Resetting CPU Usage information
+SHLL [/] $ cpuuse
+CPU Usage by thread
+   ID            NAME         SECONDS   PERCENT
+0x09010001   IDLE             0.000000    0.000
+0x0a010001   UI1              0.000000    0.000
+0x0a010002   SHLL             0.003092  100.000
+Time since last CPU Usage reset 0.003092 seconds
 @end example
 
+In the above example, the system had set idle for nearly
+a minute when the first report was generated.  The 
+@code{cpuuse -r} and @code{cpuuse} commands were pasted
+from another window so were executed with no gap between.
+In the second report, only the @code{shell} thread has
+run since the CPU Usage was reset.  It has consumed
+approximately 3.092 milliseconds of CPU time processing
+the two commands and generating the output.
+
 @subheading CONFIGURATION:
 
 @findex CONFIGURE_SHELL_NO_COMMAND_CPUUSE
@@ -119,23 +155,33 @@ stackuse
 
 @subheading DESCRIPTION:
 
-This command XXX
+This command prints a Stack Usage Report for all of the tasks
+and threads in the system.  On systems which support it, the
+usage of the interrupt stack is also included in the report.
 
 @subheading EXIT STATUS:
 
-This command returns 0 on success and non-zero if an error is encountered.
+This command always succeeds and returns 0.
 
 @subheading NOTES:
 
-NONE
+The @code{STACK_CHECKER_ON} @code{confdefs.h} constant
+must be defined when the application is configured for this
+command to have any information to report.
 
 @subheading EXAMPLES:
 
 The following is an example of how to use @code{stackuse}:
 
-@example
-EXAMPLE_TBD
-@end example
+@smallexample
+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       5116
+0xffffffff  INTR 0x023d2760 - 0x023d375f 0x00000000      4080        316
+@end smallexample
 
 @subheading CONFIGURATION:
 
@@ -188,7 +234,10 @@ perioduse [-r]
 
 @subheading DESCRIPTION:
 
-This command XXX
+This command may be used to print a statistics report on the rate
+monotonic periods in the application or to reset the rate monotonic
+period usage statistics. When invoked with the @code{-r} option, the
+usage statistics are reset.
 
 @subheading EXIT STATUS:
 
@@ -196,15 +245,44 @@ This command returns 0 on success and non-zero if an error is encountered.
 
 @subheading NOTES:
 
-NONE
+The granularity of the timing information reported is dependent
+upon the BSP and the manner in which RTEMS was built.  In the
+default RTEMS configuration, if the BSP supports nanosecond
+granularity timestamps, then the information reported will be
+highly accurate. Otherwise, the accuracy of the information
+reported is limited by the clock tick quantum.
 
 @subheading EXAMPLES:
 
 The following is an example of how to use @code{perioduse}:
 
-@example
-EXAMPLE_TBD
-@end example
+@smallexample
+SHLL [/] $ perioduse   
+Period information by period
+--- CPU times are in seconds ---
+--- Wall times are in seconds ---
+   ID     OWNER COUNT MISSED          CPU TIME                  WALL TIME
+                                    MIN/MAX/AVG                MIN/MAX/AVG
+0x42010001 TA1    502      0 0:000039/0:042650/0:004158 0:000039/0:020118/0:002848
+0x42010002 TA2    502      0 0:000041/0:042657/0:004309 0:000041/0:020116/0:002848
+0x42010003 TA3    501      0 0:000041/0:041564/0:003653 0:000041/0:020003/0:002814
+0x42010004 TA4    501      0 0:000043/0:044075/0:004911 0:000043/0:020004/0:002814
+0x42010005 TA5     10      0 0:000065/0:005413/0:002739 0:000065/1:000457/0:041058
+
+                                    MIN/MAX/AVG                MIN/MAX/AVG
+SHLL [/] $ perioduse -r
+Resetting Period Usage information
+SHLL [/] $ perioduse
+--- CPU times are in seconds ---
+--- Wall times are in seconds ---
+   ID     OWNER COUNT MISSED          CPU TIME                  WALL TIME
+                                    MIN/MAX/AVG                MIN/MAX/AVG
+0x42010001 TA1      0      0
+0x42010002 TA2      0      0
+0x42010003 TA3      0      0
+0x42010004 TA4      0      0
+0x42010005 TA5      0      0
+@end smallexample
 
 @subheading CONFIGURATION:
 
@@ -257,11 +335,22 @@ wkspace
 
 @subheading DESCRIPTION:
 
-This command XXX
+This command prints information on the current state of
+the RTEMS Executive Workspace reported.  This includes the
+following information:
+
+@itemize @bullet
+@item Number of free blocks
+@item Largest free block
+@item Total bytes free
+@item Number of used blocks
+@item Largest used block
+@item Total bytes used
+@end itemize
 
 @subheading EXIT STATUS:
 
-This command returns 0 on success and non-zero if an error is encountered.
+This command always succeeds and returns 0.
 
 @subheading NOTES:
 
@@ -272,7 +361,13 @@ NONE
 The following is an example of how to use @code{wkspace}:
 
 @example
-EXAMPLE_TBD
+SHLL [/] $ wkspace
+Number of free blocks: 1
+Largest free block:    132336
+Total bytes free:      132336
+Number of used blocks: 36
+Largest used block:    16408
+Total bytes used:      55344
 @end example
 
 @subheading CONFIGURATION:
@@ -326,23 +421,30 @@ config
 
 @subheading DESCRIPTION:
 
-This command XXX
+This command display information about the RTEMS Configuration.
 
 @subheading EXIT STATUS:
 
-This command returns 0 on success and non-zero if an error is encountered.
+This command always succeeds and returns 0.
 
 @subheading NOTES:
 
-NONE
+At this time, it does not report every configuration parameter.
+This is an area in which user submissions or sponsorship of
+a developer would be appreciated.
 
 @subheading EXAMPLES:
 
 The following is an example of how to use @code{config}:
 
-@example
-EXAMPLE_TBD
-@end example
+@smallexample
+INITIAL (startup) Configuration Info
+------------------------------------------------------------------------------
+WORKSPACE      start: 0x23d22e0;  size: 0x2dd20
+TIME           usec/tick: 10000;  tick/timeslice: 50;  tick/sec: 100
+MAXIMUMS       tasks: 20;  timers: 0;  sems: 50;  que's: 20;  ext's: 1
+               partitions: 0;  regions: 0;  ports: 0;  periods: 0
+@end smallexample
 
 @subheading CONFIGURATION:
 
@@ -395,23 +497,29 @@ itask
 
 @subheading DESCRIPTION:
 
-This command XXX
+This command prints a report on the set of initialization
+tasks and threads in the system.
 
 @subheading EXIT STATUS:
 
-This command returns 0 on success and non-zero if an error is encountered.
+This command always succeeds and returns 0.
 
 @subheading NOTES:
 
-NONE
+At this time, it includes only Classic API Initialization Tasks.
+This is an area in which user submissions or sponsorship of
+a developer would be appreciated.
 
 @subheading EXAMPLES:
 
 The following is an example of how to use @code{itask}:
 
-@example
-EXAMPLE_TBD
-@end example
+@smallexample
+SHLL [/] $ itask
+  #    NAME   ENTRY        ARGUMENT    PRIO   MODES  ATTRIBUTES   STACK SIZE
+------------------------------------------------------------------------------
+   0   UI1    [0x2002258] 0 [0x0]        1    nP      DEFAULT     4096 [0x1000]
+@end smallexample
 
 @subheading CONFIGURATION:
 
@@ -464,7 +572,11 @@ extension [id [id ...] ]
 
 @subheading DESCRIPTION:
 
-This command XXX
+When invoked with no arguments, this command prints information on
+the set of User Extensions currently active in the system.
+
+If invoked with a set of ids as arguments, then just 
+those objects are included in the information printed.
 
 @subheading EXIT STATUS:
 
@@ -476,11 +588,14 @@ NONE
 
 @subheading EXAMPLES:
 
-The following is an example of how to use @code{extension}:
+The following is an example of using the @code{extension} command
+on a system with no user extensions.
 
-@example
-EXAMPLE_TBD
-@end example
+@smallexample
+SHLL [/] $ extension
+  ID       NAME
+------------------------------------------------------------------------------
+@end smallexample
 
 @subheading CONFIGURATION:
 
@@ -533,7 +648,11 @@ task [id [id ...] ]
 
 @subheading DESCRIPTION:
 
-This command XXX
+When invoked with no arguments, this command prints information on
+the set of Classic API Tasks currently active in the system.
+
+If invoked with a set of ids as arguments, then just 
+those objects are included in the information printed.
 
 @subheading EXIT STATUS:
 
@@ -545,11 +664,16 @@ NONE
 
 @subheading EXAMPLES:
 
-The following is an example of how to use @code{task}:
+The following is an example of how to use the @code{task} on an
+application with just two Classic API tasks:
 
-@example
-EXAMPLE_TBD
-@end example
+@smallexample
+SHLL [/] $ task
+  ID       NAME   PRIO   STAT   MODES  EVENTS   WAITID  WAITARG  NOTES
+------------------------------------------------------------------------------
+0a010001   UI1      1   SUSP   P:T:nA  NONE                      
+0a010002   SHLL   100   READY  P:T:nA  NONE                      
+@end smallexample
 
 @subheading CONFIGURATION:
 
@@ -602,7 +726,11 @@ queue [id [id ... ] ]
 
 @subheading DESCRIPTION:
 
-This command XXX
+When invoked with no arguments, this command prints information on
+the set of Classic API Message Queues currently active in the system.
+
+If invoked with a set of ids as arguments, then just 
+those objects are included in the information printed.
 
 @subheading EXIT STATUS:
 
@@ -614,11 +742,14 @@ NONE
 
 @subheading EXAMPLES:
 
-The following is an example of how to use @code{queue}:
+The following is an example of using the @code{queue} command
+on a system with no Classic API Message Queues.
 
-@example
-EXAMPLE_TBD
-@end example
+@smallexample
+SHLL [/] $ queue
+  ID       NAME   ATTRIBUTES   PEND   MAXPEND  MAXSIZE
+------------------------------------------------------------------------------
+@end smallexample
 
 @subheading CONFIGURATION:
 
@@ -671,7 +802,11 @@ sema [id [id ... ] ]
 
 @subheading DESCRIPTION:
 
-This command XXX
+When invoked with no arguments, this command prints information on
+the set of Classic API Semaphores currently active in the system.
+
+If invoked with a set of objects ids as arguments, then just 
+those objects are included in the information printed.
 
 @subheading EXIT STATUS:
 
@@ -685,9 +820,19 @@ NONE
 
 The following is an example of how to use @code{sema}:
 
-@example
-EXAMPLE_TBD
-@end example
+@smallexample
+SHLL [/] $ sema
+  ID       NAME   ATTR        PRICEIL CURR_CNT HOLDID 
+------------------------------------------------------------------------------
+1a010001   LBIO   PR:BI:IN      0        1     00000000
+1a010002   TRmi   PR:BI:IN      0        1     00000000
+1a010003   LBI00  PR:BI:IN      0        1     00000000
+1a010004   TRia   PR:BI:IN      0        1     00000000
+1a010005   TRoa   PR:BI:IN      0        1     00000000
+1a010006   TRxa   <assoc.c: BAD NAME>   0    0 09010001
+1a010007   LBI01  PR:BI:IN      0        1     00000000
+1a010008   LBI02  PR:BI:IN      0        1     00000000
+@end smallexample
 
 @subheading CONFIGURATION:
 
@@ -740,7 +885,11 @@ region [id [id ... ] ]
 
 @subheading DESCRIPTION:
 
-This command XXX
+When invoked with no arguments, this command prints information on
+the set of Classic API Regions currently active in the system.
+
+If invoked with a set of object ids as arguments, then just 
+those object are included in the information printed.
 
 @subheading EXIT STATUS:
 
@@ -752,11 +901,14 @@ NONE
 
 @subheading EXAMPLES:
 
-The following is an example of how to use @code{region}:
+The following is an example of using the @code{region} command
+on a system with no user extensions.
 
-@example
-EXAMPLE_TBD
-@end example
+@smallexample
+SHLL [/] $ region
+  ID       NAME   ATTR        STARTADDR LENGTH    PAGE_SIZE USED_BLOCKS
+------------------------------------------------------------------------------
+@end smallexample
 
 @subheading CONFIGURATION:
 
@@ -809,7 +961,11 @@ part [id [id ... ] ]
 
 @subheading DESCRIPTION:
 
-This command XXX
+When invoked with no arguments, this command prints information on
+the set of Classic API Partitions currently active in the system.
+
+If invoked with a set of object ids as arguments, then just 
+those objects are included in the information printed.
 
 @subheading EXIT STATUS:
 
@@ -821,11 +977,14 @@ NONE
 
 @subheading EXAMPLES:
 
-The following is an example of how to use @code{part}:
+The following is an example of using the @code{part} command
+on a system with no user extensions.
 
-@example
-EXAMPLE_TBD
-@end example
+@smallexample
+SHLL [/] $ part
+  ID       NAME   ATTR        STARTADDR LENGTH    BUF_SIZE  USED_BLOCKS
+------------------------------------------------------------------------------
+@end smallexample
 
 @subheading CONFIGURATION:
 
@@ -878,7 +1037,8 @@ object [id [id ...] ]
 
 @subheading DESCRIPTION:
 
-This command XXX
+When invoked with a set of object ids as arguments, then 
+a report on those objects is printed.
 
 @subheading EXIT STATUS:
 
@@ -892,9 +1052,15 @@ NONE
 
 The following is an example of how to use @code{object}:
 
-@example
-EXAMPLE_TBD
-@end example
+@smallexample
+SHLL [/] $ object 0a010001 1a010002
+  ID       NAME   PRIO   STAT   MODES  EVENTS   WAITID  WAITARG  NOTES
+------------------------------------------------------------------------------
+0a010001   UI1      1   SUSP   P:T:nA  NONE                      
+  ID       NAME   ATTR        PRICEIL CURR_CNT HOLDID 
+------------------------------------------------------------------------------
+1a010002   TRmi   PR:BI:IN      0        1     00000000
+@end smallexample
 
 @subheading CONFIGURATION:
 
@@ -947,7 +1113,11 @@ driver [ major [ major ... ] ]
 
 @subheading DESCRIPTION:
 
-This command XXX
+When invoked with no arguments, this command prints information on
+the set of Device Drivers currently active in the system.
+
+If invoked with a set of major numbers as arguments, then just 
+those Device Drivers are included in the information printed.
 
 @subheading EXIT STATUS:
 
@@ -961,9 +1131,18 @@ NONE
 
 The following is an example of how to use @code{driver}:
 
-@example
-EXAMPLE_TBD
-@end example
+@smallexample
+SHLL [/] $ driver
+  Major      Entry points
+------------------------------------------------------------------------------
+  0          init: [0x200256c];  control: [0x20024c8]
+             open: [0x2002518];  close: [0x2002504]
+             read: [0x20024f0];  write: [0x20024dc]
+  1          init: [0x20023fc];  control: [0x2002448]
+             open: [0x0];  close: [0x0]
+             read: [0x0];  write: [0x0]
+SHLL [/] $ 
+@end smallexample
 
 @subheading CONFIGURATION:
 
@@ -1018,6 +1197,8 @@ dname
 
 This command XXX
 
+WARNING! XXX This command does not appear to work as of 27 February 2008.
+
 @subheading EXIT STATUS:
 
 This command returns 0 on success and non-zero if an error is encountered.
diff --git a/doc/shell/shell.texi b/doc/shell/shell.texi
index af6067eb2b..5a44678d36 100644
--- a/doc/shell/shell.texi
+++ b/doc/shell/shell.texi
@@ -82,7 +82,7 @@ This is the online version of the RTEMS Shell User's Guide.
 * General Commands::
 * File and Directory Commands::
 * Memory Commands::
-* RTEMS Commands::
+* RTEMS Specific Commands::
 * Network Commands::
 * Function and Variable Index::
 * Concept Index::