source: rtems/doc/new_chapters/rtmonuse.t @ d82f3e81

4.104.114.84.95
Last change on this file since d82f3e81 was d82f3e81, checked in by Joel Sherrill <joel.sherrill@…>, on 11/19/98 at 16:05:05

New files

  • Property mode set to 100644
File size: 7.5 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-1998.
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5@c
6@c  $Id$
7@c
8
9@chapter Rate Monotonic Period Statistics
10
11@section Introduction
12
13The rate monotonic period statistics manager is an RTEMS support
14component that maintains statistics on the execution characteristics
15of each task using a period.  The routines provided by the rate
16monotonic period statistics manager are:
17
18@itemize @bullet
19@item @code{Period_usage_Initialize} - Initialize the Period Statistics
20@item @code{Period_usage_Reset} -  Reset the Period Statistics
21@item @code{Period_usage_Update} - Update the Statistics for this Period
22@item @code{Period_usage_Dump} - Report Period Statistics Usage
23@end itemize
24
25@section Background
26
27@section Period Statistics
28
29This manager maintains a set of statistics on each period.  The following
30is a list of the information kept:
31
32@itemize @bullet
33@item @code{id}
34is the id of the period.
35
36@item @code{count}
37is the total number of periods executed.
38
39@item @code{missed_count}
40is the number of periods that were missed.
41
42@item @code{min_cpu_time}
43is the minimum amount of CPU execution time consumed
44on any execution of the periodic loop.
45
46@item @code{max_cpu_time}
47is the maximum amount of CPU execution time consumed
48on any execution of the periodic loop.
49
50@item @code{total_cpu_time}
51is the total amount of CPU execution time consumed
52by executions of the periodic loop.
53
54@item @code{min_wall_time}
55is the minimum amount of wall time that passed
56on any execution of the periodic loop.
57
58@item @code{max_wall_time}
59is the maximum amount of wall time that passed
60on any execution of the periodic loop.
61
62@item @code{total_wall_time}
63is the total amount of wall time that passed
64during executions of the periodic loop.
65
66@end itemize
67
68The above information is inexpensive to maintain and can provide very
69useful insights into the execution characteristics of a periodic
70task loop.
71
72@subsection Analysis of the Reported Information
73
74The period statistics reported must be analyzed by the user in terms
75of what the applications is.  For example, in an application where
76priorities are assigned by the Rate Monotonic Algorithm, it would
77be very undesirable for high priority (i.e. frequency) tasks to
78miss their period.  Similarly, in nearly any application, if a
79task were supposed to execute its periodic loop every 10 milliseconds
80and it averaged 11 milliseconds, then application requirements
81are not being met. 
82
83The information reported can be used to determine the "hot spots"
84in the application.  Given a period's id, the user can determine
85the length of that period.  From that information and the CPU usage,
86the user can calculate the percentage of CPU time consumed by that
87periodic task.  For example, a task executing for 20 milliseconds
88every 200 milliseconds is consuming 10 percent of the processor's
89execution time.  This is usually enough to make it a good candidate
90for optimization.
91
92However, execution time alone is not enough to gauge the value of
93optimizing a particular task.  It is more important to optimize
94a task executing 2 millisecond every 10 milliseconds (20 percent
95of the CPU) than one executing 10 milliseconds every 100 (10 percent
96of the CPU).  As a general rule of thumb, the higher frequency at
97which a task executes, the more important it is to optimize that
98task.
99
100@section Operations
101
102@subsection Initializing the Period Statistics
103
104The period statistics manager must be explicitly initialized before
105any calls to this manager.  This is done by calling the
106@code{Period_usage_Initialize} service.
107
108@subsection Updating Period Statistics
109
110It is the responsibility of each period task loop to update the statistics
111on each execution of its loop.  The following is an example of a
112simple periodic task that uses the period statistics manager:
113
114@example
115@group
116rtems_task Periodic_task()
117@{
118  rtems_name        name;
119  rtems_id          period;
120  rtems_status_code status;
121
122  name = rtems_build_name( 'P', 'E', 'R', 'D' );
123
124  (void) rate_monotonic_create( name, &period );
125
126  while ( 1 ) @{
127    if ( rate_monotonic_period( period, 100 ) == TIMEOUT )
128      break;
129
130    /* Perform some periodic actions */
131
132    /* Report statistics */
133    Period_usage_Update( period_id );
134  @}
135
136  /* missed period so delete period and SELF */
137
138  (void) rate_monotonic_delete( period );
139  (void) task_delete( SELF );
140@}
141@end group
142@end example
143
144@subsection Reporting Period Statistics
145
146The application may dynamically report the period usage for every
147period in the system by calling the @code{Period_usage_Dump} routine.
148This routine prints a table with the following information per period:
149
150@itemize @bullet
151@item period id
152@item id of the task that owns the period
153@item number of periods executed
154@item number of periods missed
155@item minimum/maximum/average cpu use per period
156@item minimum/maximum/average wall time per period
157@end itemize
158
159The following is an example of the report generated:
160
161@example
162@group
163Period information by period
164   ID      OWNER   PERIODS  MISSED    CPU TIME    WALL TIME
1650x28010001  TA1       502     0       0/1/ 1.00    0/0/0.00
1660x28010002  TA2       502     0       0/1/ 1.00    0/0/0.00
1670x28010003  TA3       502     0       0/1/ 1.00    0/0/0.00
1680x28010004  TA4       502     0       0/1/ 1.00    0/0/0.00
1690x28010005  TA5        10     0       0/1/ 0.90    0/0/0.00
170@end group
171@end example
172
173@section Routines
174
175This section details the rate monotonic period statistics manager's routines.
176A subsection is dedicated to each of this manager's routines
177and describes the calling sequence, related constants, usage,
178and status codes.
179
180@page
181@subsection Period_usage_Initialize - Initialize the Period Statistics
182
183@subheading CALLING SEQUENCE:
184
185@ifset is-C
186@example
187void Period_usage_Initialize( void );
188@end example
189@end ifset
190
191@ifset is-Ada
192@example
193An Ada interface is not currently available.
194@end example
195@end ifset
196
197@subheading STATUS CODES: NONE
198
199@subheading DESCRIPTION:
200
201This routine allocates the table used to contain the period statistics.
202This table is then initialized by calling the @code{Period_usage_Reset}
203service.
204
205@subheading NOTES:
206
207This routine invokes the @code{malloc} routine to dynamically allocate
208memory.
209
210@page
211@subsection Period_usage_Reset - Reset the Period Statistics
212
213@subheading CALLING SEQUENCE:
214
215@ifset is-C
216@example
217void Period_usage_Reset( void );
218@end example
219@end ifset
220
221@ifset is-Ada
222@example
223An Ada interface is not currently available.
224@end example
225@end ifset
226
227@subheading STATUS CODES: NONE
228
229@subheading DESCRIPTION:
230
231This routine re-initializes the period statistics table to its
232default state which is when zero period executions have occurred.
233
234@subheading NOTES:
235
236NONE
237
238@page
239@subsection Period_usage_Update - Update the Statistics for this Period
240
241@subheading CALLING SEQUENCE:
242
243@ifset is-C
244@example
245void Period_usage_Update(
246  rtems_id   id
247);
248@end example
249@end ifset
250
251@ifset is-Ada
252@example
253An Ada interface is not currently available.
254@end example
255@end ifset
256
257@subheading STATUS CODES: NONE
258
259@subheading DESCRIPTION:
260
261The @code{Period_usage_Update} routine must be invoked at the "bottom"
262of each periodic loop iteration to update the statistics.
263
264@subheading NOTES:
265
266NONE
267
268@page
269@subsection Period_usage_Dump - Report Period Statistics Usage
270
271@subheading CALLING SEQUENCE:
272
273@ifset is-C
274@example
275void Period_usage_Dump( void );
276@end example
277@end ifset
278
279@ifset is-Ada
280@example
281An Ada interface is not currently available.
282@end example
283@end ifset
284
285@subheading STATUS CODES: NONE
286
287@subheading DESCRIPTION:
288
289This routine prints out a table detailing the period statistics for
290all periods in the system.
291
292@subheading NOTES:
293
294NONE
Note: See TracBrowser for help on using the repository browser.