diff options
Diffstat (limited to 'doc/shell/rtems.t')
| -rw-r--r-- | doc/shell/rtems.t | 315 |
1 files changed, 248 insertions, 67 deletions
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. |