summaryrefslogtreecommitdiffstats
path: root/doc/new_chapters/rtmonuse.t
blob: a8cce5c48d220948a0798300039a300fbda66063 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
@c
@c  COPYRIGHT (c) 1988-1998.
@c  On-Line Applications Research Corporation (OAR).
@c  All rights reserved. 
@c
@c  $Id$
@c

@chapter Rate Monotonic Period Statistics

@section Introduction

The rate monotonic period statistics manager is an RTEMS support
component that maintains statistics on the execution characteristics
of each task using a period.  The routines provided by the rate
monotonic period statistics manager are:

@itemize @bullet
@item @code{Period_usage_Initialize} - Initialize the Period Statistics
@item @code{Period_usage_Reset} -  Reset the Period Statistics
@item @code{Period_usage_Update} - Update the Statistics for this Period
@item @code{Period_usage_Dump} - Report Period Statistics Usage
@end itemize

@section Background

@section Period Statistics

This manager maintains a set of statistics on each period.  The following
is a list of the information kept:

@itemize @bullet
@item @code{id}
is the id of the period.

@item @code{count}
is the total number of periods executed.

@item @code{missed_count}
is the number of periods that were missed.

@item @code{min_cpu_time}
is the minimum amount of CPU execution time consumed
on any execution of the periodic loop.

@item @code{max_cpu_time}
is the maximum amount of CPU execution time consumed
on any execution of the periodic loop.

@item @code{total_cpu_time}
is the total amount of CPU execution time consumed
by executions of the periodic loop.

@item @code{min_wall_time}
is the minimum amount of wall time that passed
on any execution of the periodic loop.

@item @code{max_wall_time}
is the maximum amount of wall time that passed
on any execution of the periodic loop.

@item @code{total_wall_time}
is the total amount of wall time that passed
during executions of the periodic loop.

@end itemize

The above information is inexpensive to maintain and can provide very
useful insights into the execution characteristics of a periodic
task loop.

@subsection Analysis of the Reported Information

The period statistics reported must be analyzed by the user in terms
of what the applications is.  For example, in an application where
priorities are assigned by the Rate Monotonic Algorithm, it would
be very undesirable for high priority (i.e. frequency) tasks to
miss their period.  Similarly, in nearly any application, if a 
task were supposed to execute its periodic loop every 10 milliseconds
and it averaged 11 milliseconds, then application requirements
are not being met.  

The information reported can be used to determine the "hot spots"
in the application.  Given a period's id, the user can determine
the length of that period.  From that information and the CPU usage,
the user can calculate the percentage of CPU time consumed by that
periodic task.  For example, a task executing for 20 milliseconds
every 200 milliseconds is consuming 10 percent of the processor's
execution time.  This is usually enough to make it a good candidate
for optimization.

However, execution time alone is not enough to gauge the value of
optimizing a particular task.  It is more important to optimize
a task executing 2 millisecond every 10 milliseconds (20 percent
of the CPU) than one executing 10 milliseconds every 100 (10 percent
of the CPU).  As a general rule of thumb, the higher frequency at
which a task executes, the more important it is to optimize that 
task.

@section Operations

@subsection Initializing the Period Statistics

The period statistics manager must be explicitly initialized before
any calls to this manager.  This is done by calling the
@code{Period_usage_Initialize} service.

@subsection Updating Period Statistics

It is the responsibility of each period task loop to update the statistics
on each execution of its loop.  The following is an example of a 
simple periodic task that uses the period statistics manager:

@example
@group
rtems_task Periodic_task()
@{
  rtems_name        name;
  rtems_id          period;
  rtems_status_code status;

  name = rtems_build_name( 'P', 'E', 'R', 'D' );

  (void) rate_monotonic_create( name, &period );

  while ( 1 ) @{
    if ( rate_monotonic_period( period, 100 ) == TIMEOUT )
      break;

    /* Perform some periodic actions */

    /* Report statistics */
    Period_usage_Update( period_id );
  @}

  /* missed period so delete period and SELF */

  (void) rate_monotonic_delete( period );
  (void) task_delete( SELF );
@}
@end group
@end example

@subsection Reporting Period Statistics

The application may dynamically report the period usage for every
period in the system by calling the @code{Period_usage_Dump} routine.
This routine prints a table with the following information per period:

@itemize @bullet
@item period id
@item id of the task that owns the period
@item number of periods executed
@item number of periods missed
@item minimum/maximum/average cpu use per period
@item minimum/maximum/average wall time per period
@end itemize

The following is an example of the report generated:

@example
@group
Period information by period
   ID      OWNER   PERIODS  MISSED    CPU TIME    WALL TIME
0x28010001  TA1       502     0       0/1/ 1.00    0/0/0.00
0x28010002  TA2       502     0       0/1/ 1.00    0/0/0.00
0x28010003  TA3       502     0       0/1/ 1.00    0/0/0.00
0x28010004  TA4       502     0       0/1/ 1.00    0/0/0.00
0x28010005  TA5        10     0       0/1/ 0.90    0/0/0.00
@end group
@end example

@section Routines

This section details the rate monotonic period statistics manager's routines.
A subsection is dedicated to each of this manager's routines
and describes the calling sequence, related constants, usage,
and status codes.

@page
@subsection Period_usage_Initialize - Initialize the Period Statistics

@subheading CALLING SEQUENCE:

@ifset is-C
@example
void Period_usage_Initialize( void );
@end example
@end ifset

@ifset is-Ada
@example
An Ada interface is not currently available.
@end example
@end ifset

@subheading STATUS CODES: NONE

@subheading DESCRIPTION:

This routine allocates the table used to contain the period statistics.
This table is then initialized by calling the @code{Period_usage_Reset}
service.

@subheading NOTES:

This routine invokes the @code{malloc} routine to dynamically allocate
memory. 

@page
@subsection Period_usage_Reset - Reset the Period Statistics

@subheading CALLING SEQUENCE:

@ifset is-C
@example
void Period_usage_Reset( void );
@end example
@end ifset

@ifset is-Ada
@example
An Ada interface is not currently available.
@end example
@end ifset

@subheading STATUS CODES: NONE

@subheading DESCRIPTION:

This routine re-initializes the period statistics table to its
default state which is when zero period executions have occurred.

@subheading NOTES:

NONE

@page
@subsection Period_usage_Update - Update the Statistics for this Period

@subheading CALLING SEQUENCE:

@ifset is-C
@example
void Period_usage_Update(
  rtems_id   id
);
@end example
@end ifset

@ifset is-Ada
@example
An Ada interface is not currently available.
@end example
@end ifset

@subheading STATUS CODES: NONE

@subheading DESCRIPTION:

The @code{Period_usage_Update} routine must be invoked at the "bottom"
of each periodic loop iteration to update the statistics.

@subheading NOTES:

NONE

@page
@subsection Period_usage_Dump - Report Period Statistics Usage

@subheading CALLING SEQUENCE:

@ifset is-C
@example
void Period_usage_Dump( void );
@end example
@end ifset

@ifset is-Ada
@example
An Ada interface is not currently available.
@end example
@end ifset

@subheading STATUS CODES: NONE

@subheading DESCRIPTION:

This routine prints out a table detailing the period statistics for
all periods in the system.

@subheading NOTES:

NONE