source: rtems/doc/shell/rtems.t @ 2bd71d95

4.115
Last change on this file since 2bd71d95 was 2bd71d95, checked in by Sebastian Huber <sebastian.huber@…>, on Mar 6, 2015 at 1:41:24 PM

shell: Add PROFREPORT command

  • Property mode set to 100644
File size: 36.5 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-2008.
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5
6@chapter RTEMS Specific Commands
7
8@section Introduction
9
10The RTEMS shell has the following rtems commands:
11
12@itemize @bullet
13
14@item @code{shutdown} - Shutdown the system
15@item @code{cpuuse} - print or reset per thread cpu usage
16@item @code{stackuse} - print per thread stack usage
17@item @code{perioduse} - print or reset per period usage
18@item @code{profreport} - print a profiling report
19@item @code{wkspace} - Display information on Executive Workspace
20@item @code{config} - Show the system configuration.
21@item @code{itask} - List init tasks for the system
22@item @code{extension} - Display information about extensions
23@item @code{task} - Display information about tasks
24@item @code{queue} - Display information about message queues
25@item @code{sema} - display information about semaphores
26@item @code{region} - display information about regions
27@item @code{part} - display information about partitions
28@item @code{object} - Display information about RTEMS objects
29@item @code{driver} - Display the RTEMS device driver table
30@item @code{dname} - Displays information about named drivers
31@item @code{pthread} - Displays information about POSIX threads
32
33@end itemize
34
35@section Commands
36
37This section details the RTEMS Specific Commands available.  A
38subsection is dedicated to each of the commands and
39describes the behavior and configuration of that
40command as well as providing an example usage.
41
42@c
43@c
44@c
45@page
46@subsection shutdown - Shutdown the system
47
48@pgindex shutdown
49
50@subheading SYNOPSYS:
51
52@example
53shutdown
54@end example
55
56@subheading DESCRIPTION:
57
58This command is used to shutdown the RTEMS application.
59
60@subheading EXIT STATUS:
61
62This command does not return.
63
64@subheading NOTES:
65
66
67@subheading EXAMPLES:
68
69The following is an example of how to use @code{shutdown}:
70
71@example
72SHLL [/] $ shutdown
73System shutting down at user request
74@end example
75
76The user will not see another prompt and the system will
77shutdown.
78
79@subheading CONFIGURATION:
80
81@findex CONFIGURE_SHELL_NO_COMMAND_SHUTDOWN
82@findex CONFIGURE_SHELL_COMMAND_SHUTDOWN
83
84This command is included in the default shell command set. 
85When building a custom command set, define
86@code{CONFIGURE_SHELL_COMMAND_SHUTDOWN} to have this
87command included.
88
89This command can be excluded from the shell command set by
90defining @code{CONFIGURE_SHELL_NO_COMMAND_SHUTDOWN} when all
91shell commands have been configured.
92
93@subheading PROGRAMMING INFORMATION:
94
95The configuration structure for the @code{shutdown} has the
96following prototype:
97
98@example
99extern rtems_shell_cmd_t rtems_shell_SHUTDOWN_Command;
100@end example
101
102@c
103@c
104@c
105@page
106@subsection cpuuse - print or reset per thread cpu usage
107
108@pgindex cpuuse
109
110@subheading SYNOPSYS:
111
112@example
113cpuuse [-r]
114@end example
115
116@subheading DESCRIPTION:
117
118This command may be used to print a report on the per thread
119cpu usage or to reset the per thread CPU usage statistics. When
120invoked with the @code{-r} option, the CPU usage statistics
121are reset.
122
123@subheading EXIT STATUS:
124
125This command returns 0 on success and non-zero if an error is encountered.
126
127@subheading NOTES:
128
129The granularity of the timing information reported is dependent
130upon the BSP and the manner in which RTEMS was built.  In the
131default RTEMS configuration, if the BSP supports nanosecond
132granularity timestamps, then the information reported will be
133highly accurate. Otherwise, the accuracy of the information
134reported is limited by the clock tick quantum.
135
136@subheading EXAMPLES:
137
138The following is an example of how to use @code{cpuuse}:
139
140@example
141SHLL [/] $ cpuuse
142CPU Usage by thread
143   ID            NAME         SECONDS   PERCENT
1440x09010001   IDLE            49.745393   98.953
1450x0a010001   UI1              0.000000    0.000
1460x0a010002   SHLL             0.525928    1.046
147Time since last CPU Usage reset 50.271321 seconds
148SHLL [/] $ cpuuse -r
149Resetting CPU Usage information
150SHLL [/] $ cpuuse
151CPU Usage by thread
152   ID            NAME         SECONDS   PERCENT
1530x09010001   IDLE             0.000000    0.000
1540x0a010001   UI1              0.000000    0.000
1550x0a010002   SHLL             0.003092  100.000
156Time since last CPU Usage reset 0.003092 seconds
157@end example
158
159In the above example, the system had set idle for nearly
160a minute when the first report was generated.  The
161@code{cpuuse -r} and @code{cpuuse} commands were pasted
162from another window so were executed with no gap between.
163In the second report, only the @code{shell} thread has
164run since the CPU Usage was reset.  It has consumed
165approximately 3.092 milliseconds of CPU time processing
166the two commands and generating the output.
167
168@subheading CONFIGURATION:
169
170@findex CONFIGURE_SHELL_NO_COMMAND_CPUUSE
171@findex CONFIGURE_SHELL_COMMAND_CPUUSE
172
173This command is included in the default shell command set. 
174When building a custom command set, define
175@code{CONFIGURE_SHELL_COMMAND_CPUUSE} to have this
176command included.
177
178This command can be excluded from the shell command set by
179defining @code{CONFIGURE_SHELL_NO_COMMAND_CPUUSE} when all
180shell commands have been configured.
181
182@subheading PROGRAMMING INFORMATION:
183
184@findex rtems_shell_rtems_main_cpuuse
185
186The @code{cpuuse} is implemented by a C language function
187which has the following prototype:
188
189@example
190int rtems_shell_rtems_main_cpuuse(
191  int    argc,
192  char **argv
193);
194@end example
195
196The configuration structure for the @code{cpuuse} has the
197following prototype:
198
199@example
200extern rtems_shell_cmd_t rtems_shell_CPUUSE_Command;
201@end example
202
203@c
204@c
205@c
206@page
207@subsection stackuse - print per thread stack usage
208
209@pgindex stackuse
210
211@subheading SYNOPSYS:
212
213@example
214stackuse
215@end example
216
217@subheading DESCRIPTION:
218
219This command prints a Stack Usage Report for all of the tasks
220and threads in the system.  On systems which support it, the
221usage of the interrupt stack is also included in the report.
222
223@subheading EXIT STATUS:
224
225This command always succeeds and returns 0.
226
227@subheading NOTES:
228
229The @code{CONFIGURE_STACK_CHECKER_ENABLED} @code{confdefs.h} constant
230must be defined when the application is configured for this
231command to have any information to report.
232
233@subheading EXAMPLES:
234
235The following is an example of how to use @code{stackuse}:
236
237@smallexample
238SHLL [/] $ stackuse
239Stack usage by thread
240    ID      NAME    LOW          HIGH     CURRENT     AVAILABLE     USED
2410x09010001  IDLE 0x023d89a0 - 0x023d99af 0x023d9760      4096        608
2420x0a010001  UI1  0x023d9f30 - 0x023daf3f 0x023dad18      4096       1804
2430x0a010002  SHLL 0x023db4c0 - 0x023df4cf 0x023de9d0     16384       5116
2440xffffffff  INTR 0x023d2760 - 0x023d375f 0x00000000      4080        316
245@end smallexample
246
247@subheading CONFIGURATION:
248
249@findex CONFIGURE_SHELL_NO_COMMAND_STACKUSE
250@findex CONFIGURE_SHELL_COMMAND_STACKUSE
251
252This command is included in the default shell command set. 
253When building a custom command set, define
254@code{CONFIGURE_SHELL_COMMAND_STACKUSE} to have this
255command included.
256
257This command can be excluded from the shell command set by
258defining @code{CONFIGURE_SHELL_NO_COMMAND_STACKUSE} when all
259shell commands have been configured.
260
261@subheading PROGRAMMING INFORMATION:
262
263@findex rtems_shell_rtems_main_stackuse
264
265The @code{stackuse} is implemented by a C language function
266which has the following prototype:
267
268@example
269int rtems_shell_rtems_main_stackuse(
270  int    argc,
271  char **argv
272);
273@end example
274
275The configuration structure for the @code{stackuse} has the
276following prototype:
277
278@example
279extern rtems_shell_cmd_t rtems_shell_STACKUSE_Command;
280@end example
281
282@c
283@c
284@c
285@page
286@subsection perioduse - print or reset per period usage
287
288@pgindex perioduse
289
290@subheading SYNOPSYS:
291
292@example
293perioduse [-r]
294@end example
295
296@subheading DESCRIPTION:
297
298This command may be used to print a statistics report on the rate
299monotonic periods in the application or to reset the rate monotonic
300period usage statistics. When invoked with the @code{-r} option, the
301usage statistics are reset.
302
303@subheading EXIT STATUS:
304
305This command returns 0 on success and non-zero if an error is encountered.
306
307@subheading NOTES:
308
309The granularity of the timing information reported is dependent
310upon the BSP and the manner in which RTEMS was built.  In the
311default RTEMS configuration, if the BSP supports nanosecond
312granularity timestamps, then the information reported will be
313highly accurate. Otherwise, the accuracy of the information
314reported is limited by the clock tick quantum.
315
316@subheading EXAMPLES:
317
318The following is an example of how to use @code{perioduse}:
319
320@smallexample
321SHLL [/] $ perioduse   
322Period information by period
323--- CPU times are in seconds ---
324--- Wall times are in seconds ---
325   ID     OWNER COUNT MISSED          CPU TIME                  WALL TIME
326                                    MIN/MAX/AVG                MIN/MAX/AVG
3270x42010001 TA1    502      0 0:000039/0:042650/0:004158 0:000039/0:020118/0:002848
3280x42010002 TA2    502      0 0:000041/0:042657/0:004309 0:000041/0:020116/0:002848
3290x42010003 TA3    501      0 0:000041/0:041564/0:003653 0:000041/0:020003/0:002814
3300x42010004 TA4    501      0 0:000043/0:044075/0:004911 0:000043/0:020004/0:002814
3310x42010005 TA5     10      0 0:000065/0:005413/0:002739 0:000065/1:000457/0:041058
332
333                                    MIN/MAX/AVG                MIN/MAX/AVG
334SHLL [/] $ perioduse -r
335Resetting Period Usage information
336SHLL [/] $ perioduse
337--- CPU times are in seconds ---
338--- Wall times are in seconds ---
339   ID     OWNER COUNT MISSED          CPU TIME                  WALL TIME
340                                    MIN/MAX/AVG                MIN/MAX/AVG
3410x42010001 TA1      0      0
3420x42010002 TA2      0      0
3430x42010003 TA3      0      0
3440x42010004 TA4      0      0
3450x42010005 TA5      0      0
346@end smallexample
347
348@subheading CONFIGURATION:
349
350@findex CONFIGURE_SHELL_NO_COMMAND_PERIODUSE
351@findex CONFIGURE_SHELL_COMMAND_PERIODUSE
352
353This command is included in the default shell command set. 
354When building a custom command set, define
355@code{CONFIGURE_SHELL_COMMAND_PERIODUSE} to have this
356command included.
357
358This command can be excluded from the shell command set by
359defining @code{CONFIGURE_SHELL_NO_COMMAND_PERIODUSE} when all
360shell commands have been configured.
361
362@subheading PROGRAMMING INFORMATION:
363
364@findex rtems_shell_rtems_main_perioduse
365
366The @code{perioduse} is implemented by a C language function
367which has the following prototype:
368
369@example
370int rtems_shell_rtems_main_perioduse(
371  int    argc,
372  char **argv
373);
374@end example
375
376The configuration structure for the @code{perioduse} has the
377following prototype:
378
379@example
380extern rtems_shell_cmd_t rtems_shell_PERIODUSE_Command;
381@end example
382
383@c
384@c
385@c
386@page
387@subsection profreport - print a profiling report
388
389@pgindex profreport
390
391@subheading SYNOPSYS:
392
393@example
394profreport
395@end example
396
397@subheading DESCRIPTION:
398
399This command may be used to print a profiling report.
400
401@subheading EXIT STATUS:
402
403This command returns 0.
404
405@subheading NOTES:
406
407Profiling must be enabled at build configuration time to get profiling
408information.
409
410@subheading EXAMPLES:
411
412The following is an example of how to use @code{profreport}:
413
414@smallexample
415SHLL [/] $ profreport
416<ProfilingReport name="Shell">
417  <PerCPUProfilingReport processorIndex="0">
418    <MaxThreadDispatchDisabledTime unit="ns">10447</MaxThreadDispatchDisabledTime>
419    <MeanThreadDispatchDisabledTime unit="ns">2</MeanThreadDispatchDisabledTime>
420    <TotalThreadDispatchDisabledTime unit="ns">195926627</TotalThreadDispatchDisabledTime>
421    <ThreadDispatchDisabledCount>77908688</ThreadDispatchDisabledCount>
422    <MaxInterruptDelay unit="ns">0</MaxInterruptDelay>
423    <MaxInterruptTime unit="ns">688</MaxInterruptTime>
424    <MeanInterruptTime unit="ns">127</MeanInterruptTime>
425    <TotalInterruptTime unit="ns">282651157</TotalInterruptTime>
426    <InterruptCount>2215855</InterruptCount>
427  </PerCPUProfilingReport>
428  <PerCPUProfilingReport processorIndex="1">
429    <MaxThreadDispatchDisabledTime unit="ns">9053</MaxThreadDispatchDisabledTime>
430    <MeanThreadDispatchDisabledTime unit="ns">41</MeanThreadDispatchDisabledTime>
431    <TotalThreadDispatchDisabledTime unit="ns">3053830335</TotalThreadDispatchDisabledTime>
432    <ThreadDispatchDisabledCount>73334202</ThreadDispatchDisabledCount>
433    <MaxInterruptDelay unit="ns">0</MaxInterruptDelay>
434    <MaxInterruptTime unit="ns">57</MaxInterruptTime>
435    <MeanInterruptTime unit="ns">35</MeanInterruptTime>
436    <TotalInterruptTime unit="ns">76980203</TotalInterruptTime>
437    <InterruptCount>2141179</InterruptCount>
438  </PerCPUProfilingReport>
439  <SMPLockProfilingReport name="SMP lock stats">
440    <MaxAcquireTime unit="ns">608</MaxAcquireTime>
441    <MaxSectionTime unit="ns">1387</MaxSectionTime>
442    <MeanAcquireTime unit="ns">112</MeanAcquireTime>
443    <MeanSectionTime unit="ns">338</MeanSectionTime>
444    <TotalAcquireTime unit="ns">119031</TotalAcquireTime>
445    <TotalSectionTime unit="ns">357222</TotalSectionTime>
446    <UsageCount>1055</UsageCount>
447    <ContentionCount initialQueueLength="0">1055</ContentionCount>
448    <ContentionCount initialQueueLength="1">0</ContentionCount>
449    <ContentionCount initialQueueLength="2">0</ContentionCount>
450    <ContentionCount initialQueueLength="3">0</ContentionCount>
451  </SMPLockProfilingReport>
452  <SMPLockProfilingReport name="Giant">
453    <MaxAcquireTime unit="ns">4186</MaxAcquireTime>
454    <MaxSectionTime unit="ns">7575</MaxSectionTime>
455    <MeanAcquireTime unit="ns">160</MeanAcquireTime>
456    <MeanSectionTime unit="ns">183</MeanSectionTime>
457    <TotalAcquireTime unit="ns">1772793111</TotalAcquireTime>
458    <TotalSectionTime unit="ns">2029733879</TotalSectionTime>
459    <UsageCount>11039140</UsageCount>
460    <ContentionCount initialQueueLength="0">11037655</ContentionCount>
461    <ContentionCount initialQueueLength="1">1485</ContentionCount>
462    <ContentionCount initialQueueLength="2">0</ContentionCount>
463    <ContentionCount initialQueueLength="3">0</ContentionCount>
464  </SMPLockProfilingReport>
465</ProfilingReport>
466@end smallexample
467
468@subheading CONFIGURATION:
469
470@findex CONFIGURE_SHELL_NO_COMMAND_PROFREPORT
471@findex CONFIGURE_SHELL_COMMAND_PROFREPORT
472
473When building a custom command set, define
474@code{CONFIGURE_SHELL_COMMAND_PROFREPORT} to have this
475command included.
476
477This command can be excluded from the shell command set by
478defining @code{CONFIGURE_SHELL_NO_COMMAND_PROFREPORT} when all
479shell commands have been configured.
480
481@subheading PROGRAMMING INFORMATION:
482
483The configuration structure for the @code{profreport} has the
484following prototype:
485
486@example
487extern rtems_shell_cmd_t rtems_shell_PROFREPORT_Command;
488@end example
489
490@c
491@c
492@c
493@page
494@subsection wkspace - display information on executive workspace
495
496@pgindex wkspace
497
498@subheading SYNOPSYS:
499
500@example
501wkspace
502@end example
503
504@subheading DESCRIPTION:
505
506This command prints information on the current state of
507the RTEMS Executive Workspace reported.  This includes the
508following information:
509
510@itemize @bullet
511@item Number of free blocks
512@item Largest free block
513@item Total bytes free
514@item Number of used blocks
515@item Largest used block
516@item Total bytes used
517@end itemize
518
519@subheading EXIT STATUS:
520
521This command always succeeds and returns 0.
522
523@subheading NOTES:
524
525NONE
526
527@subheading EXAMPLES:
528
529The following is an example of how to use @code{wkspace}:
530
531@example
532SHLL [/] $ wkspace
533Number of free blocks: 1
534Largest free block:    132336
535Total bytes free:      132336
536Number of used blocks: 36
537Largest used block:    16408
538Total bytes used:      55344
539@end example
540
541@subheading CONFIGURATION:
542
543@findex CONFIGURE_SHELL_NO_COMMAND_WKSPACE
544@findex CONFIGURE_SHELL_COMMAND_WKSPACE
545
546This command is included in the default shell command set. 
547When building a custom command set, define
548@code{CONFIGURE_SHELL_COMMAND_WKSPACE} to have this
549command included.
550
551This command can be excluded from the shell command set by
552defining @code{CONFIGURE_SHELL_NO_COMMAND_WKSPACE} when all
553shell commands have been configured.
554
555@subheading PROGRAMMING INFORMATION:
556
557@findex rtems_shell_rtems_main_wkspace
558
559The @code{wkspace} is implemented by a C language function
560which has the following prototype:
561
562@example
563int rtems_shell_rtems_main_wkspace(
564  int    argc,
565  char **argv
566);
567@end example
568
569The configuration structure for the @code{wkspace} has the
570following prototype:
571
572@example
573extern rtems_shell_cmd_t rtems_shell_WKSPACE_Command;
574@end example
575
576@c
577@c
578@c
579@page
580@subsection config - show the system configuration.
581
582@pgindex config
583
584@subheading SYNOPSYS:
585
586@example
587config
588@end example
589
590@subheading DESCRIPTION:
591
592This command display information about the RTEMS Configuration.
593
594@subheading EXIT STATUS:
595
596This command always succeeds and returns 0.
597
598@subheading NOTES:
599
600At this time, it does not report every configuration parameter.
601This is an area in which user submissions or sponsorship of
602a developer would be appreciated.
603
604@subheading EXAMPLES:
605
606The following is an example of how to use @code{config}:
607
608@smallexample
609INITIAL (startup) Configuration Info
610------------------------------------------------------------------------------
611WORKSPACE      start: 0x23d22e0;  size: 0x2dd20
612TIME           usec/tick: 10000;  tick/timeslice: 50;  tick/sec: 100
613MAXIMUMS       tasks: 20;  timers: 0;  sems: 50;  que's: 20;  ext's: 1
614               partitions: 0;  regions: 0;  ports: 0;  periods: 0
615@end smallexample
616
617@subheading CONFIGURATION:
618
619@findex CONFIGURE_SHELL_NO_COMMAND_CONFIG
620@findex CONFIGURE_SHELL_COMMAND_CONFIG
621
622This command is included in the default shell command set. 
623When building a custom command set, define
624@code{CONFIGURE_SHELL_COMMAND_CONFIG} to have this
625command included.
626
627This command can be excluded from the shell command set by
628defining @code{CONFIGURE_SHELL_NO_COMMAND_CONFIG} when all
629shell commands have been configured.
630
631@subheading PROGRAMMING INFORMATION:
632
633@findex rtems_shell_rtems_main_config
634
635The @code{config} is implemented by a C language function
636which has the following prototype:
637
638@example
639int rtems_shell_rtems_main_config(
640  int    argc,
641  char **argv
642);
643@end example
644
645The configuration structure for the @code{config} has the
646following prototype:
647
648@example
649extern rtems_shell_cmd_t rtems_shell_CONFIG_Command;
650@end example
651
652@c
653@c
654@c
655@page
656@subsection itask - list init tasks for the system
657
658@pgindex itask
659
660@subheading SYNOPSYS:
661
662@example
663itask
664@end example
665
666@subheading DESCRIPTION:
667
668This command prints a report on the set of initialization
669tasks and threads in the system.
670
671@subheading EXIT STATUS:
672
673This command always succeeds and returns 0.
674
675@subheading NOTES:
676
677At this time, it includes only Classic API Initialization Tasks.
678This is an area in which user submissions or sponsorship of
679a developer would be appreciated.
680
681@subheading EXAMPLES:
682
683The following is an example of how to use @code{itask}:
684
685@smallexample
686SHLL [/] $ itask
687  #    NAME   ENTRY        ARGUMENT    PRIO   MODES  ATTRIBUTES   STACK SIZE
688------------------------------------------------------------------------------
689   0   UI1    [0x2002258] 0 [0x0]        1    nP      DEFAULT     4096 [0x1000]
690@end smallexample
691
692@subheading CONFIGURATION:
693
694@findex CONFIGURE_SHELL_NO_COMMAND_ITASK
695@findex CONFIGURE_SHELL_COMMAND_ITASK
696
697This command is included in the default shell command set. 
698When building a custom command set, define
699@code{CONFIGURE_SHELL_COMMAND_ITASK} to have this
700command included.
701
702This command can be excluded from the shell command set by
703defining @code{CONFIGURE_SHELL_NO_COMMAND_ITASK} when all
704shell commands have been configured.
705
706@subheading PROGRAMMING INFORMATION:
707
708@findex rtems_shell_rtems_main_itask
709
710The @code{itask} is implemented by a C language function
711which has the following prototype:
712
713@example
714int rtems_shell_rtems_main_itask(
715  int    argc,
716  char **argv
717);
718@end example
719
720The configuration structure for the @code{itask} has the
721following prototype:
722
723@example
724extern rtems_shell_cmd_t rtems_shell_ITASK_Command;
725@end example
726
727@c
728@c
729@c
730@page
731@subsection extension - display information about extensions
732
733@pgindex extension
734
735@subheading SYNOPSYS:
736
737@example
738extension [id [id ...] ]
739@end example
740
741@subheading DESCRIPTION:
742
743When invoked with no arguments, this command prints information on
744the set of User Extensions currently active in the system.
745
746If invoked with a set of ids as arguments, then just
747those objects are included in the information printed.
748
749@subheading EXIT STATUS:
750
751This command returns 0 on success and non-zero if an error is encountered.
752
753@subheading NOTES:
754
755NONE
756
757@subheading EXAMPLES:
758
759The following is an example of using the @code{extension} command
760on a system with no user extensions.
761
762@smallexample
763SHLL [/] $ extension
764  ID       NAME
765------------------------------------------------------------------------------
766@end smallexample
767
768@subheading CONFIGURATION:
769
770@findex CONFIGURE_SHELL_NO_COMMAND_EXTENSION
771@findex CONFIGURE_SHELL_COMMAND_EXTENSION
772
773This command is included in the default shell command set. 
774When building a custom command set, define
775@code{CONFIGURE_SHELL_COMMAND_EXTENSION} to have this
776command included.
777
778This command can be excluded from the shell command set by
779defining @code{CONFIGURE_SHELL_NO_COMMAND_EXTENSION} when all
780shell commands have been configured.
781
782@subheading PROGRAMMING INFORMATION:
783
784@findex rtems_shell_rtems_main_extension
785
786The @code{extension} is implemented by a C language function
787which has the following prototype:
788
789@example
790int rtems_shell_rtems_main_extension(
791  int    argc,
792  char **argv
793);
794@end example
795
796The configuration structure for the @code{extension} has the
797following prototype:
798
799@example
800extern rtems_shell_cmd_t rtems_shell_EXTENSION_Command;
801@end example
802
803@c
804@c
805@c
806@page
807@subsection task - display information about tasks
808
809@pgindex task
810
811@subheading SYNOPSYS:
812
813@example
814task [id [id ...] ]
815@end example
816
817@subheading DESCRIPTION:
818
819When invoked with no arguments, this command prints information on
820the set of Classic API Tasks currently active in the system.
821
822If invoked with a set of ids as arguments, then just
823those objects are included in the information printed.
824
825@subheading EXIT STATUS:
826
827This command returns 0 on success and non-zero if an error is encountered.
828
829@subheading NOTES:
830
831NONE
832
833@subheading EXAMPLES:
834
835The following is an example of how to use the @code{task} on an
836application with just two Classic API tasks:
837
838@smallexample
839SHLL [/] $ task
840  ID       NAME   PRIO   STAT   MODES  EVENTS   WAITID  WAITARG  NOTES
841------------------------------------------------------------------------------
8420a010001   UI1      1   SUSP   P:T:nA  NONE                     
8430a010002   SHLL   100   READY  P:T:nA  NONE                     
844@end smallexample
845
846@subheading CONFIGURATION:
847
848@findex CONFIGURE_SHELL_NO_COMMAND_TASK
849@findex CONFIGURE_SHELL_COMMAND_TASK
850
851This command is included in the default shell command set. 
852When building a custom command set, define
853@code{CONFIGURE_SHELL_COMMAND_TASK} to have this
854command included.
855
856This command can be excluded from the shell command set by
857defining @code{CONFIGURE_SHELL_NO_COMMAND_TASK} when all
858shell commands have been configured.
859
860@subheading PROGRAMMING INFORMATION:
861
862@findex rtems_shell_rtems_main_task
863
864The @code{task} is implemented by a C language function
865which has the following prototype:
866
867@example
868int rtems_shell_rtems_main_task(
869  int    argc,
870  char **argv
871);
872@end example
873
874The configuration structure for the @code{task} has the
875following prototype:
876
877@example
878extern rtems_shell_cmd_t rtems_shell_TASK_Command;
879@end example
880
881@c
882@c
883@c
884@page
885@subsection queue - display information about message queues
886
887@pgindex queue
888
889@subheading SYNOPSYS:
890
891@example
892queue [id [id ... ] ]
893@end example
894
895@subheading DESCRIPTION:
896
897When invoked with no arguments, this command prints information on
898the set of Classic API Message Queues currently active in the system.
899
900If invoked with a set of ids as arguments, then just
901those objects are included in the information printed.
902
903@subheading EXIT STATUS:
904
905This command returns 0 on success and non-zero if an error is encountered.
906
907@subheading NOTES:
908
909NONE
910
911@subheading EXAMPLES:
912
913The following is an example of using the @code{queue} command
914on a system with no Classic API Message Queues.
915
916@smallexample
917SHLL [/] $ queue
918  ID       NAME   ATTRIBUTES   PEND   MAXPEND  MAXSIZE
919------------------------------------------------------------------------------
920@end smallexample
921
922@subheading CONFIGURATION:
923
924@findex CONFIGURE_SHELL_NO_COMMAND_QUEUE
925@findex CONFIGURE_SHELL_COMMAND_QUEUE
926
927This command is included in the default shell command set. 
928When building a custom command set, define
929@code{CONFIGURE_SHELL_COMMAND_QUEUE} to have this
930command included.
931
932This command can be excluded from the shell command set by
933defining @code{CONFIGURE_SHELL_NO_COMMAND_QUEUE} when all
934shell commands have been configured.
935
936@subheading PROGRAMMING INFORMATION:
937
938@findex rtems_shell_rtems_main_queue
939
940The @code{queue} is implemented by a C language function
941which has the following prototype:
942
943@example
944int rtems_shell_rtems_main_queue(
945  int    argc,
946  char **argv
947);
948@end example
949
950The configuration structure for the @code{queue} has the
951following prototype:
952
953@example
954extern rtems_shell_cmd_t rtems_shell_QUEUE_Command;
955@end example
956
957@c
958@c
959@c
960@page
961@subsection sema - display information about semaphores
962
963@pgindex sema
964
965@subheading SYNOPSYS:
966
967@example
968sema [id [id ... ] ]
969@end example
970
971@subheading DESCRIPTION:
972
973When invoked with no arguments, this command prints information on
974the set of Classic API Semaphores currently active in the system.
975
976If invoked with a set of objects ids as arguments, then just
977those objects are included in the information printed.
978
979@subheading EXIT STATUS:
980
981This command returns 0 on success and non-zero if an error is encountered.
982
983@subheading NOTES:
984
985NONE
986
987@subheading EXAMPLES:
988
989The following is an example of how to use @code{sema}:
990
991@smallexample
992SHLL [/] $ sema
993  ID       NAME   ATTR        PRICEIL CURR_CNT HOLDID
994------------------------------------------------------------------------------
9951a010001   LBIO   PR:BI:IN      0        1     00000000
9961a010002   TRmi   PR:BI:IN      0        1     00000000
9971a010003   LBI00  PR:BI:IN      0        1     00000000
9981a010004   TRia   PR:BI:IN      0        1     00000000
9991a010005   TRoa   PR:BI:IN      0        1     00000000
10001a010006   TRxa   <assoc.c: BAD NAME>   0    0 09010001
10011a010007   LBI01  PR:BI:IN      0        1     00000000
10021a010008   LBI02  PR:BI:IN      0        1     00000000
1003@end smallexample
1004
1005@subheading CONFIGURATION:
1006
1007@findex CONFIGURE_SHELL_NO_COMMAND_SEMA
1008@findex CONFIGURE_SHELL_COMMAND_SEMA
1009
1010This command is included in the default shell command set. 
1011When building a custom command set, define
1012@code{CONFIGURE_SHELL_COMMAND_SEMA} to have this
1013command included.
1014
1015This command can be excluded from the shell command set by
1016defining @code{CONFIGURE_SHELL_NO_COMMAND_SEMA} when all
1017shell commands have been configured.
1018
1019@subheading PROGRAMMING INFORMATION:
1020
1021@findex rtems_shell_rtems_main_sema
1022
1023The @code{sema} is implemented by a C language function
1024which has the following prototype:
1025
1026@example
1027int rtems_shell_rtems_main_sema(
1028  int    argc,
1029  char **argv
1030);
1031@end example
1032
1033The configuration structure for the @code{sema} has the
1034following prototype:
1035
1036@example
1037extern rtems_shell_cmd_t rtems_shell_SEMA_Command;
1038@end example
1039
1040@c
1041@c
1042@c
1043@page
1044@subsection region - display information about regions
1045
1046@pgindex region
1047
1048@subheading SYNOPSYS:
1049
1050@example
1051region [id [id ... ] ]
1052@end example
1053
1054@subheading DESCRIPTION:
1055
1056When invoked with no arguments, this command prints information on
1057the set of Classic API Regions currently active in the system.
1058
1059If invoked with a set of object ids as arguments, then just
1060those object are included in the information printed.
1061
1062@subheading EXIT STATUS:
1063
1064This command returns 0 on success and non-zero if an error is encountered.
1065
1066@subheading NOTES:
1067
1068NONE
1069
1070@subheading EXAMPLES:
1071
1072The following is an example of using the @code{region} command
1073on a system with no user extensions.
1074
1075@smallexample
1076SHLL [/] $ region
1077  ID       NAME   ATTR        STARTADDR LENGTH    PAGE_SIZE USED_BLOCKS
1078------------------------------------------------------------------------------
1079@end smallexample
1080
1081@subheading CONFIGURATION:
1082
1083@findex CONFIGURE_SHELL_NO_COMMAND_REGION
1084@findex CONFIGURE_SHELL_COMMAND_REGION
1085
1086This command is included in the default shell command set. 
1087When building a custom command set, define
1088@code{CONFIGURE_SHELL_COMMAND_REGION} to have this
1089command included.
1090
1091This command can be excluded from the shell command set by
1092defining @code{CONFIGURE_SHELL_NO_COMMAND_REGION} when all
1093shell commands have been configured.
1094
1095@subheading PROGRAMMING INFORMATION:
1096
1097@findex rtems_shell_rtems_main_region
1098
1099The @code{region} is implemented by a C language function
1100which has the following prototype:
1101
1102@example
1103int rtems_shell_rtems_main_region(
1104  int    argc,
1105  char **argv
1106);
1107@end example
1108
1109The configuration structure for the @code{region} has the
1110following prototype:
1111
1112@example
1113extern rtems_shell_cmd_t rtems_shell_REGION_Command;
1114@end example
1115
1116@c
1117@c
1118@c
1119@page
1120@subsection part - display information about partitions
1121
1122@pgindex part
1123
1124@subheading SYNOPSYS:
1125
1126@example
1127part [id [id ... ] ]
1128@end example
1129
1130@subheading DESCRIPTION:
1131
1132When invoked with no arguments, this command prints information on
1133the set of Classic API Partitions currently active in the system.
1134
1135If invoked with a set of object ids as arguments, then just
1136those objects are included in the information printed.
1137
1138@subheading EXIT STATUS:
1139
1140This command returns 0 on success and non-zero if an error is encountered.
1141
1142@subheading NOTES:
1143
1144NONE
1145
1146@subheading EXAMPLES:
1147
1148The following is an example of using the @code{part} command
1149on a system with no user extensions.
1150
1151@smallexample
1152SHLL [/] $ part
1153  ID       NAME   ATTR        STARTADDR LENGTH    BUF_SIZE  USED_BLOCKS
1154------------------------------------------------------------------------------
1155@end smallexample
1156
1157@subheading CONFIGURATION:
1158
1159@findex CONFIGURE_SHELL_NO_COMMAND_PART
1160@findex CONFIGURE_SHELL_COMMAND_PART
1161
1162This command is included in the default shell command set. 
1163When building a custom command set, define
1164@code{CONFIGURE_SHELL_COMMAND_PART} to have this
1165command included.
1166
1167This command can be excluded from the shell command set by
1168defining @code{CONFIGURE_SHELL_NO_COMMAND_PART} when all
1169shell commands have been configured.
1170
1171@subheading PROGRAMMING INFORMATION:
1172
1173@findex rtems_shell_rtems_main_part
1174
1175The @code{part} is implemented by a C language function
1176which has the following prototype:
1177
1178@example
1179int rtems_shell_rtems_main_part(
1180  int    argc,
1181  char **argv
1182);
1183@end example
1184
1185The configuration structure for the @code{part} has the
1186following prototype:
1187
1188@example
1189extern rtems_shell_cmd_t rtems_shell_PART_Command;
1190@end example
1191
1192@c
1193@c
1194@c
1195@page
1196@subsection object - display information about rtems objects
1197
1198@pgindex object
1199
1200@subheading SYNOPSYS:
1201
1202@example
1203object [id [id ...] ]
1204@end example
1205
1206@subheading DESCRIPTION:
1207
1208When invoked with a set of object ids as arguments, then
1209a report on those objects is printed.
1210
1211@subheading EXIT STATUS:
1212
1213This command returns 0 on success and non-zero if an error is encountered.
1214
1215@subheading NOTES:
1216
1217NONE
1218
1219@subheading EXAMPLES:
1220
1221The following is an example of how to use @code{object}:
1222
1223@smallexample
1224SHLL [/] $ object 0a010001 1a010002
1225  ID       NAME   PRIO   STAT   MODES  EVENTS   WAITID  WAITARG  NOTES
1226------------------------------------------------------------------------------
12270a010001   UI1      1   SUSP   P:T:nA  NONE                     
1228  ID       NAME   ATTR        PRICEIL CURR_CNT HOLDID
1229------------------------------------------------------------------------------
12301a010002   TRmi   PR:BI:IN      0        1     00000000
1231@end smallexample
1232
1233@subheading CONFIGURATION:
1234
1235@findex CONFIGURE_SHELL_NO_COMMAND_OBJECT
1236@findex CONFIGURE_SHELL_COMMAND_OBJECT
1237
1238This command is included in the default shell command set. 
1239When building a custom command set, define
1240@code{CONFIGURE_SHELL_COMMAND_OBJECT} to have this
1241command included.
1242
1243This command can be excluded from the shell command set by
1244defining @code{CONFIGURE_SHELL_NO_COMMAND_OBJECT} when all
1245shell commands have been configured.
1246
1247@subheading PROGRAMMING INFORMATION:
1248
1249@findex rtems_shell_rtems_main_object
1250
1251The @code{object} is implemented by a C language function
1252which has the following prototype:
1253
1254@example
1255int rtems_shell_rtems_main_object(
1256  int    argc,
1257  char **argv
1258);
1259@end example
1260
1261The configuration structure for the @code{object} has the
1262following prototype:
1263
1264@example
1265extern rtems_shell_cmd_t rtems_shell_OBJECT_Command;
1266@end example
1267
1268@c
1269@c
1270@c
1271@page
1272@subsection driver - display the rtems device driver table
1273
1274@pgindex driver
1275
1276@subheading SYNOPSYS:
1277
1278@example
1279driver [ major [ major ... ] ]
1280@end example
1281
1282@subheading DESCRIPTION:
1283
1284When invoked with no arguments, this command prints information on
1285the set of Device Drivers currently active in the system.
1286
1287If invoked with a set of major numbers as arguments, then just
1288those Device Drivers are included in the information printed.
1289
1290@subheading EXIT STATUS:
1291
1292This command returns 0 on success and non-zero if an error is encountered.
1293
1294@subheading NOTES:
1295
1296NONE
1297
1298@subheading EXAMPLES:
1299
1300The following is an example of how to use @code{driver}:
1301
1302@smallexample
1303SHLL [/] $ driver
1304  Major      Entry points
1305------------------------------------------------------------------------------
1306  0          init: [0x200256c];  control: [0x20024c8]
1307             open: [0x2002518];  close: [0x2002504]
1308             read: [0x20024f0];  write: [0x20024dc]
1309  1          init: [0x20023fc];  control: [0x2002448]
1310             open: [0x0];  close: [0x0]
1311             read: [0x0];  write: [0x0]
1312SHLL [/] $
1313@end smallexample
1314
1315@subheading CONFIGURATION:
1316
1317@findex CONFIGURE_SHELL_NO_COMMAND_DRIVER
1318@findex CONFIGURE_SHELL_COMMAND_DRIVER
1319
1320This command is included in the default shell command set. 
1321When building a custom command set, define
1322@code{CONFIGURE_SHELL_COMMAND_DRIVER} to have this
1323command included.
1324
1325This command can be excluded from the shell command set by
1326defining @code{CONFIGURE_SHELL_NO_COMMAND_DRIVER} when all
1327shell commands have been configured.
1328
1329@subheading PROGRAMMING INFORMATION:
1330
1331@findex rtems_shell_rtems_main_driver
1332
1333The @code{driver} is implemented by a C language function
1334which has the following prototype:
1335
1336@example
1337int rtems_shell_rtems_main_driver(
1338  int    argc,
1339  char **argv
1340);
1341@end example
1342
1343The configuration structure for the @code{driver} has the
1344following prototype:
1345
1346@example
1347extern rtems_shell_cmd_t rtems_shell_DRIVER_Command;
1348@end example
1349
1350@c
1351@c
1352@c
1353@page
1354@subsection dname - displays information about named drivers
1355
1356@pgindex dname
1357
1358@subheading SYNOPSYS:
1359
1360@example
1361dname
1362@end example
1363
1364@subheading DESCRIPTION:
1365
1366This command XXX
1367
1368WARNING! XXX This command does not appear to work as of 27 February 2008.
1369
1370@subheading EXIT STATUS:
1371
1372This command returns 0 on success and non-zero if an error is encountered.
1373
1374@subheading NOTES:
1375
1376NONE
1377
1378@subheading EXAMPLES:
1379
1380The following is an example of how to use @code{dname}:
1381
1382@example
1383EXAMPLE_TBD
1384@end example
1385
1386@subheading CONFIGURATION:
1387
1388@findex CONFIGURE_SHELL_NO_COMMAND_DNAME
1389@findex CONFIGURE_SHELL_COMMAND_DNAME
1390
1391This command is included in the default shell command set. 
1392When building a custom command set, define
1393@code{CONFIGURE_SHELL_COMMAND_DNAME} to have this
1394command included.
1395
1396This command can be excluded from the shell command set by
1397defining @code{CONFIGURE_SHELL_NO_COMMAND_DNAME} when all
1398shell commands have been configured.
1399
1400@subheading PROGRAMMING INFORMATION:
1401
1402@findex rtems_shell_rtems_main_dname
1403
1404The @code{dname} is implemented by a C language function
1405which has the following prototype:
1406
1407@example
1408int rtems_shell_rtems_main_dname(
1409  int    argc,
1410  char **argv
1411);
1412@end example
1413
1414The configuration structure for the @code{dname} has the
1415following prototype:
1416
1417@example
1418extern rtems_shell_cmd_t rtems_shell_DNAME_Command;
1419@end example
1420
1421@c
1422@c
1423@c
1424@page
1425@subsection pthread - display information about POSIX threads
1426
1427@pgindex pthread
1428
1429@subheading SYNOPSYS:
1430
1431@example
1432pthread [id [id ...] ]
1433@end example
1434
1435@subheading DESCRIPTION:
1436
1437When invoked with no arguments, this command prints information on
1438the set of POSIX API threads currently active in the system.
1439
1440If invoked with a set of ids as arguments, then just
1441those objects are included in the information printed.
1442
1443@subheading EXIT STATUS:
1444
1445This command returns 0 on success and non-zero if an error is encountered.
1446
1447@subheading NOTES:
1448
1449This command is only available when the POSIX API is configured.
1450
1451@subheading EXAMPLES:
1452
1453The following is an example of how to use the @code{task} on an
1454application with four POSIX threads:
1455
1456@smallexample
1457SHLL [/] $ pthread
1458  ID       NAME           PRI  STATE MODES   EVENTS    WAITID  WAITARG  NOTES
1459------------------------------------------------------------------------------
14600b010002   Main           133 READY  P:T:nA    NONE   43010001 0x7b1148
14610b010003   ISR            133 Wcvar  P:T:nA    NONE   43010003 0x7b1148
14620b01000c                  133 READY  P:T:nA    NONE   33010002 0x7b1148
14630b01000d                  133 Wmutex P:T:nA    NONE   33010002 0x7b1148
1464
1465@end smallexample
1466
1467@subheading CONFIGURATION:
1468
1469This command is part of the monitor commands which are always
1470available in the shell.
1471
1472@subheading PROGRAMMING INFORMATION:
1473
1474This command is not directly available for invocation.
1475
Note: See TracBrowser for help on using the repository browser.