1 | @c |
---|
2 | @c COPYRIGHT (c) 1988-2002. |
---|
3 | @c On-Line Applications Research Corporation (OAR). |
---|
4 | @c All rights reserved. |
---|
5 | @c |
---|
6 | @c $Id$ |
---|
7 | @c |
---|
8 | |
---|
9 | @chapter CPU Usage Statistics |
---|
10 | |
---|
11 | @section Introduction |
---|
12 | |
---|
13 | The CPU usage statistics manager is an RTEMS support |
---|
14 | component that provides a convenient way to manipulate |
---|
15 | the CPU usage information associated with each task |
---|
16 | The routines provided by the CPU usage statistics manager are: |
---|
17 | |
---|
18 | @itemize @bullet |
---|
19 | @item @code{CPU_usage_Dump} - Report CPU Usage Statistics |
---|
20 | @item @code{CPU_usage_Reset} - Reset CPU Usage Statistics |
---|
21 | @end itemize |
---|
22 | |
---|
23 | @section Background |
---|
24 | |
---|
25 | @section Operations |
---|
26 | |
---|
27 | @section Report CPU Usage Statistics |
---|
28 | |
---|
29 | @subsection Reporting Period Statistics |
---|
30 | |
---|
31 | The application may dynamically report the CPU usage for every |
---|
32 | task in the system by calling the @code{CPU_usage_Dump} routine. |
---|
33 | This routine prints a table with the following information per task: |
---|
34 | |
---|
35 | @itemize @bullet |
---|
36 | @item task id |
---|
37 | @item task name |
---|
38 | @item number of clock ticks executed |
---|
39 | @item percentage of time consumed by this task |
---|
40 | @end itemize |
---|
41 | |
---|
42 | The following is an example of the report generated: |
---|
43 | |
---|
44 | @example |
---|
45 | @group |
---|
46 | CPU Usage by thread |
---|
47 | ID NAME TICKS PERCENT |
---|
48 | 0x04010001 IDLE 0 0.000 |
---|
49 | 0x08010002 TA1 1203 0.748 |
---|
50 | 0x08010003 TA2 203 0.126 |
---|
51 | 0x08010004 TA3 202 0.126 |
---|
52 | |
---|
53 | Ticks since last reset = 1600 |
---|
54 | |
---|
55 | Total Units = 1608 |
---|
56 | @end group |
---|
57 | @end example |
---|
58 | |
---|
59 | Notice that the "Total Units" is greater than the ticks per reset. |
---|
60 | This is an artifact of the way in which RTEMS keeps track of CPU |
---|
61 | usage. When a task is context switched into the CPU, the number |
---|
62 | of clock ticks it has executed is incremented. While the task |
---|
63 | is executing, this number is incremented on each clock tick. |
---|
64 | Otherwise, if a task begins and completes execution between |
---|
65 | successive clock ticks, there would be no way to tell that it |
---|
66 | executed at all. |
---|
67 | |
---|
68 | Another thing to keep in mind when looking at idle time, is that |
---|
69 | many systems -- especially during debug -- have a task providing |
---|
70 | some type of debug interface. It is usually fine to think of the |
---|
71 | total idle time as being the sum of the IDLE task and a debug |
---|
72 | task that will not be included in a production build of an application. |
---|
73 | |
---|
74 | @section Reset CPU Usage Statistics |
---|
75 | |
---|
76 | Invoking the @code{CPU_usage_Reset} routine resets the CPU usage |
---|
77 | statistics for all tasks in the system. |
---|
78 | |
---|
79 | @section Directives |
---|
80 | |
---|
81 | This section details the CPU usage statistics manager's directives. |
---|
82 | A subsection is dedicated to each of this manager's directives |
---|
83 | and describes the calling sequence, related constants, usage, |
---|
84 | and status codes. |
---|
85 | |
---|
86 | @page |
---|
87 | @subsection CPU_usage_Dump - Report CPU Usage Statistics |
---|
88 | |
---|
89 | @subheading CALLING SEQUENCE: |
---|
90 | |
---|
91 | @ifset is-C |
---|
92 | @example |
---|
93 | void CPU_usage_Dump( void ); |
---|
94 | @end example |
---|
95 | @end ifset |
---|
96 | |
---|
97 | @ifset is-Ada |
---|
98 | @example |
---|
99 | An Ada interface is not currently available. |
---|
100 | @end example |
---|
101 | @end ifset |
---|
102 | |
---|
103 | @subheading STATUS CODES: NONE |
---|
104 | |
---|
105 | @subheading DESCRIPTION: |
---|
106 | |
---|
107 | This routine prints out a table detailing the CPU usage statistics for |
---|
108 | all tasks in the system. |
---|
109 | |
---|
110 | @subheading NOTES: |
---|
111 | |
---|
112 | NONE |
---|
113 | |
---|
114 | @page |
---|
115 | @subsection CPU_usage_Reset - Reset CPU Usage Statistics |
---|
116 | |
---|
117 | @subheading CALLING SEQUENCE: |
---|
118 | |
---|
119 | @ifset is-C |
---|
120 | @example |
---|
121 | void CPU_usage_Reset( void ); |
---|
122 | @end example |
---|
123 | @end ifset |
---|
124 | |
---|
125 | @ifset is-Ada |
---|
126 | @example |
---|
127 | An Ada interface is not currently available. |
---|
128 | @end example |
---|
129 | @end ifset |
---|
130 | |
---|
131 | @subheading STATUS CODES: NONE |
---|
132 | |
---|
133 | @subheading DESCRIPTION: |
---|
134 | |
---|
135 | This routine re-initializes the CPU usage statistics for all tasks |
---|
136 | in the system to their initial state. The initial state is that |
---|
137 | a task has not executed and thus has consumed no CPU time. |
---|
138 | default state which is when zero period executions have occurred. |
---|
139 | |
---|
140 | @subheading NOTES: |
---|
141 | |
---|
142 | NONE |
---|