From 88d2967e3ee93ba5a5226535240768036c96d8d5 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Wed, 27 Feb 2008 21:46:27 +0000 Subject: 2008-02-27 Joel Sherrill * 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. --- doc/shell/file.t | 5 + doc/shell/general.t | 118 ++++++++++--------- doc/shell/memory.t | 202 +++++++++++++++++++++++++++------ doc/shell/network.t | 4 + doc/shell/rtems.t | 315 ++++++++++++++++++++++++++++++++++++++++----------- doc/shell/shell.texi | 2 +- 6 files changed, 488 insertions(+), 158 deletions(-) (limited to 'doc/shell') 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 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:: -- cgit v1.2.3