source: rtems/doc/user/rtmon.t @ 1b03eed

4.8
Last change on this file since 1b03eed was 1b03eed, checked in by Glenn Humphrey <glenn.humphrey@…>, on 10/26/07 at 21:34:57

2007-10-26 Glenn Humphrey <glenn.humphrey@…>

  • user/rtmon.t: Fix report output.

2007-10-25 Glenn Humphrey <glenn.humphrey@…>

  • user/barrier.t, user/clock.t, user/concepts.t, user/cpuuse.t, user/init.t, user/intr.t, user/io.t, user/mp.t, user/rtmon.t, user/sem.t, user/stackchk.t, user/task.t, user/timer.t: Updated the Ada documentation to reflect the current binding.
  • Property mode set to 100644
File size: 47.1 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-2007.
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5@c
6@c  $Id$
7@c
8
9@c
10@c  Open Issues
11@c    - nicen up the tables
12@c    - use math mode to print formulas
13@c
14
15@chapter Rate Monotonic Manager
16
17@cindex rate mononitonic tasks
18@cindex periodic tasks
19
20@section Introduction
21
22The rate monotonic manager provides facilities to implement tasks which execute
23in a periodic fashion.  Critically, it also gathers information about the
24execution of those periods and can provide important statistics to the
25user which can be used to analyze and tune the application.  The directives
26provided by the rate monotonic manager are:
27
28@itemize @bullet
29@item @code{@value{DIRPREFIX}rate_monotonic_create} - Create a rate monotonic period
30@item @code{@value{DIRPREFIX}rate_monotonic_ident} - Get ID of a period
31@item @code{@value{DIRPREFIX}rate_monotonic_cancel} - Cancel a period
32@item @code{@value{DIRPREFIX}rate_monotonic_delete} - Delete a rate monotonic period
33@item @code{@value{DIRPREFIX}rate_monotonic_period} - Conclude current/Start next period
34@item @code{@value{DIRPREFIX}rate_monotonic_get_status} - Obtain status from a period
35@item @code{@value{DIRPREFIX}rate_monotonic_get_statistics} - Obtain statistics from a period
36@item @code{@value{DIRPREFIX}rate_monotonic_reset_statistics} - Reset statistics for a period
37@item @code{@value{DIRPREFIX}rate_monotonic_reset_all_statistics} - Reset statistics for all periods
38@item @code{@value{DIRPREFIX}rate_monotonic_report_statistics} - Print period statistics report
39@end itemize
40
41@section Background
42
43The rate monotonic manager provides facilities to
44manage the execution of periodic tasks.  This manager was
45designed to support application designers who utilize the Rate
46Monotonic Scheduling Algorithm (RMS) to ensure that their
47periodic tasks will meet their deadlines, even under transient
48overload conditions.  Although designed for hard real-time
49systems, the services provided by the rate monotonic manager may
50be used by any application which requires periodic tasks.
51
52@subsection Rate Monotonic Manager Required Support
53
54A clock tick is required to support the functionality provided by this manager.
55
56@subsection Period Statistics
57
58This manager maintains a set of statistics on each period.  These
59statistics are reset implictly at period creation time and may be
60reset or obtained at any time by the application.  The following
61is a list of the information kept:
62
63@itemize @bullet
64@item @code{owner}
65is the id of the thread that owns this period.
66
67@item @code{count}
68is the total number of periods executed.
69
70@item @code{missed_count}
71is the number of periods that were missed.
72
73@item @code{min_cpu_time}
74is the minimum amount of CPU execution time consumed
75on any execution of the periodic loop.
76
77@item @code{max_cpu_time}
78is the maximum amount of CPU execution time consumed
79on any execution of the periodic loop.
80
81@item @code{total_cpu_time}
82is the total amount of CPU execution time consumed
83by executions of the periodic loop.
84
85@item @code{min_wall_time}
86is the minimum amount of wall time that passed
87on any execution of the periodic loop.
88
89@item @code{max_wall_time}
90is the maximum amount of wall time that passed
91on any execution of the periodic loop.
92
93@item @code{total_wall_time}
94is the total amount of wall time that passed
95during executions of the periodic loop.
96
97@end itemize
98
99The period statistics information is inexpensive to maintain
100and can provide very useful insights into the execution
101characteristics of a periodic task loop.  But it is just information.
102The period statistics reported must be analyzed by the user in terms
103of what the applications is.  For example, in an application where
104priorities are assigned by the Rate Monotonic Algorithm, it would
105be very undesirable for high priority (i.e. frequency) tasks to
106miss their period.  Similarly, in nearly any application, if a
107task were supposed to execute its periodic loop every 10 milliseconds
108and it averaged 11 milliseconds, then application requirements
109are not being met.
110
111The information reported can be used to determine the "hot spots"
112in the application.  Given a period's id, the user can determine
113the length of that period.  From that information and the CPU usage,
114the user can calculate the percentage of CPU time consumed by that
115periodic task.  For example, a task executing for 20 milliseconds
116every 200 milliseconds is consuming 10 percent of the processor's
117execution time.  This is usually enough to make it a good candidate
118for optimization.
119
120However, execution time alone is not enough to gauge the value of
121optimizing a particular task.  It is more important to optimize
122a task executing 2 millisecond every 10 milliseconds (20 percent
123of the CPU) than one executing 10 milliseconds every 100 (10 percent
124of the CPU).  As a general rule of thumb, the higher frequency at
125which a task executes, the more important it is to optimize that
126task.
127
128@subsection Rate Monotonic Manager Definitions
129
130@cindex periodic task, definition
131
132A periodic task is one which must be executed at a
133regular interval.  The interval between successive iterations of
134the task is referred to as its period.  Periodic tasks can be
135characterized by the length of their period and execution time.
136The period and execution time of a task can be used to determine
137the processor utilization for that task.  Processor utilization
138is the percentage of processor time used and can be calculated
139on a per-task or system-wide basis.  Typically, the task's
140worst-case execution time will be less than its period.  For
141example, a periodic task's requirements may state that it should
142execute for 10 milliseconds every 100 milliseconds.  Although
143the execution time may be the average, worst, or best case, the
144worst-case execution time is more appropriate for use when
145analyzing system behavior under transient overload conditions.
146
147@cindex aperiodic task, definition
148
149In contrast, an aperiodic task executes at irregular
150intervals and has only a soft deadline.  In other words, the
151deadlines for aperiodic tasks are not rigid, but adequate
152response times are desirable.  For example, an aperiodic task
153may process user input from a terminal.
154
155@cindex sporadic task, definition
156
157Finally, a sporadic task is an aperiodic task with a
158hard deadline and minimum interarrival time.  The minimum
159interarrival time is the minimum period of time which exists
160between successive iterations of the task.  For example, a
161sporadic task could be used to process the pressing of a fire
162button on a joystick.  The mechanical action of the fire button
163ensures a minimum time period between successive activations,
164but the missile must be launched by a hard deadline.
165
166@subsection Rate Monotonic Scheduling Algorithm
167
168@cindex Rate Monotonic Scheduling Algorithm, definition
169@cindex RMS Algorithm, definition
170
171The Rate Monotonic Scheduling Algorithm (RMS) is
172important to real-time systems designers because it allows one
173to guarantee that a set of tasks is schedulable.  A set of tasks
174is said to be schedulable if all of the tasks can meet their
175deadlines.  RMS provides a set of rules which can be used to
176perform a guaranteed schedulability analysis for a task set.
177This analysis determines whether a task set is schedulable under
178worst-case conditions and emphasizes the predictability of the
179system's behavior.  It has been proven that:
180
181@itemize @code{ }
182@b{RMS is an optimal static priority algorithm for
183scheduling independent, preemptible, periodic tasks
184on a single processor.}
185@end itemize
186
187RMS is optimal in the sense that if a set of tasks
188can be scheduled by any static priority algorithm, then RMS will
189be able to schedule that task set.  RMS bases it schedulability
190analysis on the processor utilization level below which all
191deadlines can be met.
192
193RMS calls for the static assignment of task
194priorities based upon their period.  The shorter a task's
195period, the higher its priority.  For example, a task with a 1
196millisecond period has higher priority than a task with a 100
197millisecond period.  If two tasks have the same period, then RMS
198does not distinguish between the tasks.  However, RTEMS
199specifies that when given tasks of equal priority, the task
200which has been ready longest will execute first.  RMS's priority
201assignment scheme does not provide one with exact numeric values
202for task priorities.  For example, consider the following task
203set and priority assignments:
204
205@ifset use-ascii
206@example
207@group
208+--------------------+---------------------+---------------------+
209|        Task        |       Period        |      Priority       |
210|                    |  (in milliseconds)  |                     |
211+--------------------+---------------------+---------------------+
212|         1          |         100         |         Low         |
213+--------------------+---------------------+---------------------+
214|         2          |          50         |       Medium        |
215+--------------------+---------------------+---------------------+
216|         3          |          50         |       Medium        |
217+--------------------+---------------------+---------------------+
218|         4          |          25         |        High         |
219+--------------------+---------------------+---------------------+
220@end group
221@end example
222@end ifset
223
224@ifset use-tex
225@sp 1
226@tex
227\centerline{\vbox{\offinterlineskip\halign{
228\vrule\strut#&
229\hbox to 0.75in{\enskip\hfil#\hfil}&
230\vrule#&
231\hbox to 1.25in{\enskip\hfil#\hfil}&
232\vrule#&
233\hbox to 1.25in{\enskip\hfil#\hfil}&
234\vrule#\cr\noalign{\hrule}
235&\bf Task&& \bf Period && \bf Priority &\cr
236& && \bf (in milliseconds) && &\cr\noalign{\hrule}
237& 1 && 100 && Low &\cr\noalign{\hrule}
238& 2 && 50 && Medium &\cr\noalign{\hrule}
239& 3 && 50 && Medium &\cr\noalign{\hrule}
240& 4 && 25 && High &\cr\noalign{\hrule}
241}}\hfil}
242@end tex
243@end ifset
244
245@ifset use-html
246@html
247<CENTER>
248  <TABLE COLS=3 WIDTH="80%" BORDER=2>
249<TR><TD ALIGN=center><STRONG>Task</STRONG></TD>
250    <TD ALIGN=center><STRONG>Period (in milliseconds)</STRONG></TD>
251    <TD ALIGN=center><STRONG>Priority</STRONG></TD></TR>
252<TR><TD ALIGN=center>1</TD>
253    <TD ALIGN=center>100 </TD>
254    <TD ALIGN=center>Low</TD></TR>
255<TR><TD ALIGN=center>2</TD>
256    <TD ALIGN=center>50 </TD>
257    <TD ALIGN=center>Medium</TD></TR>
258<TR><TD ALIGN=center>3</TD>
259    <TD ALIGN=center>50 </TD>
260    <TD ALIGN=center>Medium</TD></TR>
261<TR><TD ALIGN=center>4</TD>
262    <TD ALIGN=center>25 </TD>
263    <TD ALIGN=center>High</TD></TR>
264  </TABLE>
265</CENTER>
266@end html
267@end ifset
268
269RMS only calls for task 1 to have the lowest
270priority, task 4 to have the highest priority, and tasks 2 and 3
271to have an equal priority between that of tasks 1 and 4.  The
272actual RTEMS priorities assigned to the tasks must only adhere
273to those guidelines.
274
275Many applications have tasks with both hard and soft
276deadlines.  The tasks with hard deadlines are typically referred
277to as the critical task set, with the soft deadline tasks being
278the non-critical task set.  The critical task set can be
279scheduled using RMS, with the non-critical tasks not executing
280under transient overload, by simply assigning priorities such
281that the lowest priority critical task (i.e. longest period) has
282a higher priority than the highest priority non-critical task.
283Although RMS may be used to assign priorities to the
284non-critical tasks, it is not necessary.  In this instance,
285schedulability is only guaranteed for the critical task set.
286
287@subsection Schedulability Analysis
288
289@cindex RMS schedulability analysis
290
291RMS allows application designers to ensure that tasks
292can meet all deadlines, even under transient overload, without
293knowing exactly when any given task will execute by applying
294proven schedulability analysis rules.
295
296@subsubsection Assumptions
297
298The schedulability analysis rules for RMS were
299developed based on the following assumptions:
300
301
302@itemize @bullet
303@item The requests for all tasks for which hard deadlines
304exist are periodic, with a constant interval between requests.
305
306@item Each task must complete before the next request for it
307occurs.
308
309@item The tasks are independent in that a task does not depend
310on the initiation or completion of requests for other tasks.
311
312@item The execution time for each task without preemption or
313interruption is constant and does not vary.
314
315@item Any non-periodic tasks in the system are special.  These
316tasks displace periodic tasks while executing and do not have
317hard, critical deadlines.
318@end itemize
319
320Once the basic schedulability analysis is understood,
321some of the above assumptions can be relaxed and the
322side-effects accounted for.
323
324@subsubsection Processor Utilization Rule
325
326@cindex RMS Processor Utilization Rule
327
328The Processor Utilization Rule requires that
329processor utilization be calculated based upon the period and
330execution time of each task.  The fraction of processor time
331spent executing task index is Time(index) / Period(index).  The
332processor utilization can be calculated as follows:
333
334@example
335@group
336Utilization = 0
337
338for index = 1 to maximum_tasks
339  Utilization = Utilization + (Time(index)/Period(index))
340@end group
341@end example
342
343To ensure schedulability even under transient
344overload, the processor utilization must adhere to the following
345rule:
346
347@example
348Utilization = maximum_tasks * (2**(1/maximum_tasks) - 1)
349@end example
350
351As the number of tasks increases, the above formula
352approaches ln(2) for a worst-case utilization factor of
353approximately 0.693.  Many tasks sets can be scheduled with a
354greater utilization factor.  In fact, the average processor
355utilization threshold for a randomly generated task set is
356approximately 0.88.
357
358@subsubsection Processor Utilization Rule Example
359
360This example illustrates the application of the
361Processor Utilization Rule to an application with three critical
362periodic tasks.  The following table details the RMS priority,
363period, execution time, and processor utilization for each task:
364
365@ifset use-ascii
366@example
367@group
368    +------------+----------+--------+-----------+-------------+
369    |    Task    |   RMS    | Period | Execution |  Processor  |
370    |            | Priority |        |   Time    | Utilization |
371    +------------+----------+--------+-----------+-------------+
372    |     1      |   High   |  100   |    15     |    0.15     |
373    +------------+----------+--------+-----------+-------------+
374    |     2      |  Medium  |  200   |    50     |    0.25     |
375    +------------+----------+--------+-----------+-------------+
376    |     3      |   Low    |  300   |   100     |    0.33     |
377    +------------+----------+--------+-----------+-------------+
378@end group
379@end example
380@end ifset
381
382@ifset use-tex
383@sp 1
384@tex
385\centerline{\vbox{\offinterlineskip\halign{
386\vrule\strut#&
387\hbox to 0.75in{\enskip\hfil#\hfil}&
388\vrule#&
389\hbox to 0.75in{\enskip\hfil#\hfil}&
390\vrule#&
391\hbox to 0.75in{\enskip\hfil#\hfil}&
392\vrule#&
393\hbox to 1.00in{\enskip\hfil#\hfil}&
394\vrule#&
395\hbox to 1.00in{\enskip\hfil#\hfil}&
396\vrule#\cr\noalign{\hrule}
397&\bf Task&& \bf RMS && \bf Period && \bf Execution &&\bf Processor&\cr
398& && \bf Priority && &&\bf Time &&\bf Utilization &\cr\noalign{\hrule}
399& 1 && High && 100 && 15 && 0.15 &\cr\noalign{\hrule}
400& 2 && Medium && 200 && 50 && 0.25 &\cr\noalign{\hrule}
401& 3 && Low && 300 && 100 && 0.33 &\cr\noalign{\hrule}
402}}\hfil}
403@end tex
404@end ifset
405 
406@ifset use-html
407@html
408<CENTER>
409  <TABLE COLS=5 WIDTH="80%" BORDER=2>
410<TR><TD ALIGN=center><STRONG>Task</STRONG></TD>
411    <TD ALIGN=center><STRONG>RMS Priority</STRONG></TD>
412    <TD ALIGN=center><STRONG>Period</STRONG></TD>
413    <TD ALIGN=center><STRONG>Execution Time</STRONG></TD>
414    <TD ALIGN=center><STRONG>Processor Utilization</STRONG></TD></TR>
415<TR><TD ALIGN=center>1</TD>
416    <TD ALIGN=center>High</TD>
417    <TD ALIGN=center>100</TD>
418    <TD ALIGN=center>15</TD>
419    <TD ALIGN=center>0.15</TD></TR>
420<TR><TD ALIGN=center>2</TD>
421    <TD ALIGN=center>Medium</TD>
422    <TD ALIGN=center>200</TD>
423    <TD ALIGN=center>50</TD>
424    <TD ALIGN=center>0.25</TD></TR>
425<TR><TD ALIGN=center>3</TD>
426    <TD ALIGN=center>Low</TD>
427    <TD ALIGN=center>300</TD>
428    <TD ALIGN=center>100</TD>
429    <TD ALIGN=center>0.33</TD></TR>
430  </TABLE>
431</CENTER>
432@end html
433@end ifset
434
435The total processor utilization for this task set is
4360.73 which is below the upper bound of 3 * (2**(1/3) - 1), or
4370.779, imposed by the Processor Utilization Rule.  Therefore,
438this task set is guaranteed to be schedulable using RMS.
439
440@subsubsection First Deadline Rule
441
442@cindex RMS First Deadline Rule
443
444If a given set of tasks do exceed the processor
445utilization upper limit imposed by the Processor Utilization
446Rule, they can still be guaranteed to meet all their deadlines
447by application of the First Deadline Rule.  This rule can be
448stated as follows:
449
450For a given set of independent periodic tasks, if
451each task meets its first deadline when all tasks are started at
452the same time, then the deadlines will always be met for any
453combination of start times.
454
455A key point with this rule is that ALL periodic tasks
456are assumed to start at the exact same instant in time.
457Although this assumption may seem to be invalid,  RTEMS makes it
458quite easy to ensure.  By having a non-preemptible user
459initialization task, all application tasks, regardless of
460priority, can be created and started before the initialization
461deletes itself.  This technique ensures that all tasks begin to
462compete for execution time at the same instant -- when the user
463initialization task deletes itself.
464
465@subsubsection First Deadline Rule Example
466
467The First Deadline Rule can ensure schedulability
468even when the Processor Utilization Rule fails.  The example
469below is a modification of the Processor Utilization Rule
470example where task execution time has been increased from 15 to
47125 units.  The following table details the RMS priority, period,
472execution time, and processor utilization for each task:
473
474@ifset use-ascii
475@example
476@group
477    +------------+----------+--------+-----------+-------------+
478    |    Task    |   RMS    | Period | Execution |  Processor  |
479    |            | Priority |        |   Time    | Utilization |
480    +------------+----------+--------+-----------+-------------+
481    |     1      |   High   |  100   |    25     |    0.25     |
482    +------------+----------+--------+-----------+-------------+
483    |     2      |  Medium  |  200   |    50     |    0.25     |
484    +------------+----------+--------+-----------+-------------+
485    |     3      |   Low    |  300   |   100     |    0.33     |
486    +------------+----------+--------+-----------+-------------+
487@end group
488@end example
489@end ifset
490
491@ifset use-tex
492@sp 1
493@tex
494\centerline{\vbox{\offinterlineskip\halign{
495\vrule\strut#&
496\hbox to 0.75in{\enskip\hfil#\hfil}&
497\vrule#&
498\hbox to 0.75in{\enskip\hfil#\hfil}&
499\vrule#&
500\hbox to 0.75in{\enskip\hfil#\hfil}&
501\vrule#&
502\hbox to 1.00in{\enskip\hfil#\hfil}&
503\vrule#&
504\hbox to 1.00in{\enskip\hfil#\hfil}&
505\vrule#\cr\noalign{\hrule}
506&\bf Task&& \bf RMS && \bf Period && \bf Execution &&\bf Processor&\cr
507& && \bf Priority && &&\bf Time &&\bf Utilization &\cr\noalign{\hrule}
508& 1 && High && 100 && 25 && 0.25 &\cr\noalign{\hrule}
509& 2 && Medium && 200 && 50 && 0.25 &\cr\noalign{\hrule}
510& 3 && Low && 300 && 100 && 0.33 &\cr\noalign{\hrule}
511}}\hfil}
512@end tex
513@end ifset
514 
515@ifset use-html
516@html
517<CENTER>
518  <TABLE COLS=5 WIDTH="80%" BORDER=2>
519<TR><TD ALIGN=center><STRONG>Task</STRONG></TD>
520    <TD ALIGN=center><STRONG>RMS Priority</STRONG></TD>
521    <TD ALIGN=center><STRONG>Period</STRONG></TD>
522    <TD ALIGN=center><STRONG>Execution Time</STRONG></TD>
523    <TD ALIGN=center><STRONG>Processor Utilization</STRONG></TD></TR>
524<TR><TD ALIGN=center>1</TD>
525    <TD ALIGN=center>High</TD>
526    <TD ALIGN=center>100</TD>
527    <TD ALIGN=center>25</TD>
528    <TD ALIGN=center>0.25</TD></TR>
529<TR><TD ALIGN=center>2</TD>
530    <TD ALIGN=center>Medium</TD>
531    <TD ALIGN=center>200</TD>
532    <TD ALIGN=center>50</TD>
533    <TD ALIGN=center>0.25</TD></TR>
534<TR><TD ALIGN=center>3</TD>
535    <TD ALIGN=center>Low</TD>
536    <TD ALIGN=center>300</TD>
537    <TD ALIGN=center>100</TD>
538    <TD ALIGN=center>0.33</TD></TR>
539  </TABLE>
540</CENTER>
541@end html
542@end ifset
543
544The total processor utilization for the modified task
545set is 0.83 which is above the upper bound of 3 * (2**(1/3) - 1),
546or 0.779, imposed by the Processor Utilization Rule.  Therefore,
547this task set is not guaranteed to be schedulable using RMS.
548However, the First Deadline Rule can guarantee the
549schedulability of this task set.  This rule calls for one to
550examine each occurrence of deadline until either all tasks have
551met their deadline or one task failed to meet its first
552deadline.  The following table details the time of each deadline
553occurrence, the maximum number of times each task may have run,
554the total execution time, and whether all the deadlines have
555been met.
556
557@ifset use-ascii
558@example
559@group
560+----------+------+------+------+----------------------+---------------+
561| Deadline | Task | Task | Task |        Total         | All Deadlines |
562|   Time   |  1   |  2   |  3   |    Execution Time    |     Met?      |
563+----------+------+------+------+----------------------+---------------+
564|   100    |  1   |  1   |  1   |  25 + 50 + 100 = 175 |      NO       |
565+----------+------+------+------+----------------------+---------------+
566|   200    |  2   |  1   |  1   |  50 + 50 + 100 = 200 |     YES       |
567+----------+------+------+------+----------------------+---------------+
568@end group
569@end example
570@end ifset
571
572@ifset use-tex
573@sp 1
574@tex
575\centerline{\vbox{\offinterlineskip\halign{
576\vrule\strut#&
577\hbox to 0.75in{\enskip\hfil#\hfil}&
578\vrule#&
579\hbox to 0.75in{\enskip\hfil#\hfil}&
580\vrule#&
581\hbox to 0.75in{\enskip\hfil#\hfil}&
582\vrule#&
583\hbox to 0.75in{\enskip\hfil#\hfil}&
584\vrule#&
585\hbox to 2.00in{\enskip\hfil#\hfil}&
586\vrule#&
587\hbox to 1.00in{\enskip\hfil#\hfil}&
588\vrule#\cr\noalign{\hrule}
589&\bf Deadline&& \bf Task &&\bf Task&&\bf Task&&\bf Total          &&\bf All Deadlines &\cr
590&\bf Time    && \bf 1    &&\bf 2   &&\bf 3   &&\bf Execution Time &&\bf Net?&\cr\noalign{\hrule}
591& 100&& 1 && 1 && 1 && 25 + 50 + 100 = 175 && NO &\cr\noalign{\hrule}
592& 200&& 2 && 1 && 1 && 50 + 50 + 100 = 200 && YES &\cr\noalign{\hrule}
593}}\hfil}
594@end tex
595@end ifset
596 
597@ifset use-html
598@html
599<CENTER>
600  <TABLE COLS=6 WIDTH="80%" BORDER=2>
601<TR><TD ALIGN=center><STRONG>Deadline Time</STRONG></TD>
602    <TD ALIGN=center><STRONG>Task 1</STRONG></TD>
603    <TD ALIGN=center><STRONG>Task 2</STRONG></TD>
604    <TD ALIGN=center><STRONG>Task 3</STRONG></TD>
605    <TD ALIGN=center><STRONG>Total Execution Time</STRONG></TD>
606    <TD ALIGN=center><STRONG>All Deadlines Met?</STRONG></TD></TR>
607<TR><TD ALIGN=center>100</TD>
608    <TD ALIGN=center>1</TD>
609    <TD ALIGN=center>1</TD>
610    <TD ALIGN=center>1</TD>
611    <TD ALIGN=center>25 + 50 + 100 = 175</TD>
612    <TD ALIGN=center>NO</TD></TR>
613<TR><TD ALIGN=center>200</TD>
614    <TD ALIGN=center>2</TD>
615    <TD ALIGN=center>1</TD>
616    <TD ALIGN=center>1</TD>
617    <TD ALIGN=center>50 + 50 + 100 = 175</TD>
618    <TD ALIGN=center>YES</TD></TR>
619  </TABLE>
620</CENTER>
621@end html
622@end ifset
623
624The key to this analysis is to recognize when each
625task will execute.  For example at time 100, task 1 must have
626met its first deadline, but tasks 2 and 3 may also have begun
627execution.  In this example, at time 100 tasks 1 and 2 have
628completed execution and thus have met their first deadline.
629Tasks 1 and 2 have used (25 + 50) = 75 time units, leaving (100
630- 75) = 25 time units for task 3 to begin.  Because task 3 takes
631100 ticks to execute, it will not have completed execution at
632time 100.  Thus at time 100, all of the tasks except task 3 have
633met their first deadline.
634
635At time 200, task 1 must have met its second deadline
636and task 2 its first deadline.  As a result, of the first 200
637time units, task 1 uses (2 * 25) = 50 and task 2 uses 50,
638leaving (200 - 100) time units for task 3.  Task 3 requires 100
639time units to execute, thus it will have completed execution at
640time 200.  Thus, all of the tasks have met their first deadlines
641at time 200, and the task set is schedulable using the First
642Deadline Rule.
643
644@subsubsection Relaxation of Assumptions
645
646The assumptions used to develop the RMS
647schedulability rules are uncommon in most real-time systems.
648For example, it was assumed that tasks have constant unvarying
649execution time.  It is possible to relax this assumption, simply
650by using the worst-case execution time of each task.
651
652Another assumption is that the tasks are independent.
653This means that the tasks do not wait for one another or
654contend for resources.  This assumption can be relaxed by
655accounting for the amount of time a task spends waiting to
656acquire resources.  Similarly, each task's execution time must
657account for any I/O performed and any RTEMS directive calls.
658
659In addition, the assumptions did not account for the
660time spent executing interrupt service routines.  This can be
661accounted for by including all the processor utilization by
662interrupt service routines in the utilization calculation.
663Similarly, one should also account for the impact of delays in
664accessing local memory caused by direct memory access and other
665processors accessing local dual-ported memory.
666
667The assumption that nonperiodic tasks are used only
668for initialization or failure-recovery can be relaxed by placing
669all periodic tasks in the critical task set.  This task set can
670be scheduled and analyzed using RMS.  All nonperiodic tasks are
671placed in the non-critical task set.  Although the critical task
672set can be guaranteed to execute even under transient overload,
673the non-critical task set is not guaranteed to execute.
674
675In conclusion, the application designer must be fully
676cognizant of the system and its run-time behavior when
677performing schedulability analysis for a system using RMS.
678Every hardware and software factor which impacts the execution
679time of each task must be accounted for in the schedulability
680analysis.
681
682@subsubsection Further Reading
683
684For more information on Rate Monotonic Scheduling and
685its schedulability analysis, the reader is referred to the
686following:
687
688@itemize @code{ }
689@item @cite{C. L. Liu and J. W. Layland. "Scheduling Algorithms for
690Multiprogramming in a Hard Real Time Environment." @b{Journal of
691the Association of Computing Machinery}. January 1973. pp. 46-61.}
692
693@item @cite{John Lehoczky, Lui Sha, and Ye Ding. "The Rate Monotonic
694Scheduling Algorithm: Exact Characterization and Average Case
695Behavior."  @b{IEEE Real-Time Systems Symposium}. 1989. pp. 166-171.}
696
697@item @cite{Lui Sha and John Goodenough. "Real-Time Scheduling
698Theory and Ada."  @b{IEEE Computer}. April 1990. pp. 53-62.}
699
700@item @cite{Alan Burns. "Scheduling hard real-time systems: a
701review."  @b{Software Engineering Journal}. May 1991. pp. 116-128.}
702@end itemize
703
704@section Operations
705
706@subsection Creating a Rate Monotonic Period
707
708The @code{@value{DIRPREFIX}rate_monotonic_create} directive creates a rate
709monotonic period which is to be used by the calling task to
710delineate a period.  RTEMS allocates a Period Control Block
711(PCB) from the PCB free list.  This data structure is used by
712RTEMS to manage the newly created rate monotonic period.  RTEMS
713returns a unique period ID to the application which is used by
714other rate monotonic manager directives to access this rate
715monotonic period.
716
717@subsection Manipulating a Period
718
719The @code{@value{DIRPREFIX}rate_monotonic_period} directive is used to
720establish and maintain periodic execution utilizing a previously
721created rate monotonic period.   Once initiated by the
722@code{@value{DIRPREFIX}rate_monotonic_period} directive, the period is
723said to run until it either expires or is reinitiated.  The state of the rate
724monotonic period results in one of the following scenarios:
725
726@itemize @bullet
727@item If the rate monotonic period is running, the calling
728task will be blocked for the remainder of the outstanding period
729and, upon completion of that period, the period will be
730reinitiated with the specified period.
731
732@item If the rate monotonic period is not currently running
733and has not expired, it is initiated with a length of period
734ticks and the calling task returns immediately.
735
736@item If the rate monotonic period has expired before the task
737invokes the @code{@value{DIRPREFIX}rate_monotonic_period} directive,
738the period will be initiated with a length of period ticks and the calling task
739returns immediately with a timeout error status.
740
741@end itemize
742
743@subsection Obtaining the Status of a Period
744
745If the @code{@value{DIRPREFIX}rate_monotonic_period} directive is invoked
746with a period of @code{@value{RPREFIX}PERIOD_STATUS} ticks, the current
747state of the specified rate monotonic period will be returned.  The following
748table details the relationship between the period's status and
749the directive status code returned by the
750@code{@value{DIRPREFIX}rate_monotonic_period}
751directive:
752
753@itemize @bullet
754@item @code{@value{RPREFIX}SUCCESSFUL} - period is running
755
756@item @code{@value{RPREFIX}TIMEOUT} - period has expired
757
758@item @code{@value{RPREFIX}NOT_DEFINED} - period has never been initiated
759@end itemize
760
761Obtaining the status of a rate monotonic period does
762not alter the state or length of that period.
763
764@subsection Canceling a Period
765
766The @code{@value{DIRPREFIX}rate_monotonic_cancel} directive is used to stop
767the period maintained by the specified rate monotonic period.
768The period is stopped and the rate monotonic period can be
769reinitiated using the @code{@value{DIRPREFIX}rate_monotonic_period} directive.
770
771@subsection Deleting a Rate Monotonic Period
772
773The @code{@value{DIRPREFIX}rate_monotonic_delete} directive is used to delete
774a rate monotonic period.  If the period is running and has not
775expired, the period is automatically canceled.  The rate
776monotonic period's control block is returned to the PCB free
777list when it is deleted.  A rate monotonic period can be deleted
778by a task other than the task which created the period.
779
780@subsection Examples
781
782The following sections illustrate common uses of rate
783monotonic periods to construct periodic tasks.
784
785@subsection Simple Periodic Task
786
787This example consists of a single periodic task
788which, after initialization, executes every 100 clock ticks.
789
790@page
791@example
792rtems_task Periodic_task(rtems_task_argument arg)
793@{
794  rtems_name        name;
795  rtems_id          period;
796  rtems_status_code status;
797
798  name = rtems_build_name( 'P', 'E', 'R', 'D' );
799
800  status = rtems_rate_monotonic_create( name, &period );
801  if ( status != RTEMS_STATUS_SUCCESSFUL ) @{
802    printf( "rtems_monotonic_create failed with status of %d.\n", rc );
803    exit( 1 );
804  @}
805
806
807  while ( 1 ) @{
808    if ( rtems_rate_monotonic_period( period, 100 ) == RTEMS_TIMEOUT )
809      break;
810
811    /* Perform some periodic actions */
812  @}
813
814  /* missed period so delete period and SELF */
815
816  status = rtems_rate_monotonic_delete( period );
817  if ( status != RTEMS_STATUS_SUCCESSFUL ) @{
818    printf( "rtems_rate_monotonic_delete failed with status of %d.\n", status );
819    exit( 1 );
820  @}
821
822  status = rtems_task_delete( SELF );    /* should not return */
823  printf( "rtems_task_delete returned with status of %d.\n", status );
824  exit( 1 );
825@}
826@end example
827
828
829The above task creates a rate monotonic period as
830part of its initialization.  The first time the loop is
831executed, the @code{@value{DIRPREFIX}rate_monotonic_period}
832directive will initiate the period for 100 ticks and return
833immediately.  Subsequent invocations of the
834@code{@value{DIRPREFIX}rate_monotonic_period} directive will result
835in the task blocking for the remainder of the 100 tick period.
836If, for any reason, the body of the loop takes more than 100
837ticks to execute, the @code{@value{DIRPREFIX}rate_monotonic_period}
838directive will return the @code{@value{RPREFIX}TIMEOUT} status. 
839If the above task misses its deadline, it will delete the rate
840monotonic period and itself.
841
842@subsection Task with Multiple Periods
843
844This example consists of a single periodic task
845which, after initialization, performs two sets of actions every
846100 clock ticks.  The first set of actions is performed in the
847first forty clock ticks of every 100 clock ticks, while the
848second set of actions is performed between the fortieth and
849seventieth clock ticks.  The last thirty clock ticks are not
850used by this task.
851
852@page
853@example
854rtems_task Periodic_task(rtems_task_argument arg)
855@{
856  rtems_name        name_1, name_2;
857  rtems_id          period_1, period_2;
858  rtems_status_code status;
859
860  name_1 = rtems_build_name( 'P', 'E', 'R', '1' );
861  name_2 = rtems_build_name( 'P', 'E', 'R', '2' );
862
863  (void ) rtems_rate_monotonic_create( name_1, &period_1 );
864  (void ) rtems_rate_monotonic_create( name_2, &period_2 );
865
866  while ( 1 ) @{
867    if ( rtems_rate_monotonic_period( period_1, 100 ) == TIMEOUT )
868      break;
869
870    if ( rtems_rate_monotonic_period( period_2, 40 ) == TIMEOUT )
871      break;
872
873    /*
874     *  Perform first set of actions between clock
875     *  ticks 0 and 39 of every 100 ticks.
876     */
877
878    if ( rtems_rate_monotonic_period( period_2, 30 ) == TIMEOUT )
879      break;
880
881    /*
882     *  Perform second set of actions between clock 40 and 69
883     *  of every 100 ticks.  THEN ...
884     *
885     *  Check to make sure we didn't miss the period_2 period.
886     */
887
888    if ( rtems_rate_monotonic_period( period_2, STATUS ) == TIMEOUT )
889      break;
890
891    (void) rtems_rate_monotonic_cancel( period_2 );
892  @}
893
894  /* missed period so delete period and SELF */
895
896  (void ) rtems_rate_monotonic_delete( period_1 );
897  (void ) rtems_rate_monotonic_delete( period_2 );
898  (void ) task_delete( SELF );
899@}
900@end example
901
902The above task creates two rate monotonic periods as
903part of its initialization.  The first time the loop is
904executed, the @code{@value{DIRPREFIX}rate_monotonic_period}
905directive will initiate the period_1 period for 100 ticks
906and return immediately.  Subsequent invocations of the
907@code{@value{DIRPREFIX}rate_monotonic_period} directive
908for period_1 will result in the task blocking for the remainder
909of the 100 tick period.  The period_2 period is used to control
910the execution time of the two sets of actions within each 100
911tick period established by period_1.  The
912@code{@value{DIRPREFIX}rate_monotonic_cancel( period_2 )}
913call is performed to ensure that the period_2 period
914does not expire while the task is blocked on the period_1
915period.  If this cancel operation were not performed, every time
916the @code{@value{DIRPREFIX}rate_monotonic_period( period_2, 40 )}
917call is executed, except for the initial one, a directive status
918of @code{@value{RPREFIX}TIMEOUT} is returned.  It is important to
919note that every time this call is made, the period_2 period will be
920initiated immediately and the task will not block.
921
922If, for any reason, the task misses any deadline, the
923@code{@value{DIRPREFIX}rate_monotonic_period} directive will
924return the @code{@value{RPREFIX}TIMEOUT}
925directive status.  If the above task misses its deadline, it
926will delete the rate monotonic periods and itself.
927
928@section Directives
929
930This section details the rate monotonic manager's
931directives.  A subsection is dedicated to each of this manager's
932directives and describes the calling sequence, related
933constants, usage, and status codes.
934
935@c
936@c
937@c
938@page
939@subsection RATE_MONOTONIC_CREATE - Create a rate monotonic period
940
941@cindex create a period
942
943@subheading CALLING SEQUENCE:
944
945@ifset is-C
946@findex rtems_rate_monotonic_create
947@example
948rtems_status_code rtems_rate_monotonic_create(
949  rtems_name  name,
950  rtems_id   *id
951);
952@end example
953@end ifset
954
955@ifset is-Ada
956@example
957procedure Rate_Monotonic_Create (
958   Name   : in     RTEMS.Name;
959   ID     :    out RTEMS.ID;
960   Result :    out RTEMS.Status_Codes
961);
962@end example
963@end ifset
964
965@subheading DIRECTIVE STATUS CODES:
966@code{@value{RPREFIX}SUCCESSFUL} - rate monotonic period created successfully@*
967@code{@value{RPREFIX}INVALID_NAME} - invalid task name@*
968@code{@value{RPREFIX}TOO_MANY} - too many periods created
969
970@subheading DESCRIPTION:
971
972This directive creates a rate monotonic period.  The
973assigned rate monotonic id is returned in id.  This id is used
974to access the period with other rate monotonic manager
975directives.  For control and maintenance of the rate monotonic
976period, RTEMS allocates a PCB from the local PCB free pool and
977initializes it.
978
979@subheading NOTES:
980
981This directive will not cause the calling task to be
982preempted.
983
984@c
985@c
986@c
987@page
988@subsection RATE_MONOTONIC_IDENT - Get ID of a period
989
990@cindex get ID of a period
991@cindex obtain ID of a period
992
993@subheading CALLING SEQUENCE:
994
995@ifset is-C
996@findex rtems_rate_monotonic_ident
997@example
998rtems_status_code rtems_rate_monotonic_ident(
999  rtems_name  name,
1000  rtems_id   *id
1001);
1002@end example
1003@end ifset
1004
1005@ifset is-Ada
1006@example
1007procedure Rate_Monotonic_Ident (
1008   Name   : in     RTEMS.Name;
1009   ID     :    out RTEMS.ID;
1010   Result :    out RTEMS.Status_Codes
1011);
1012@end example
1013@end ifset
1014
1015@subheading DIRECTIVE STATUS CODES:
1016@code{@value{RPREFIX}SUCCESSFUL} - period identified successfully@*
1017@code{@value{RPREFIX}INVALID_NAME} - period name not found
1018
1019@subheading DESCRIPTION:
1020
1021This directive obtains the period id associated with
1022the period name to be acquired.  If the period name is not
1023unique, then the period id will match one of the periods with
1024that name.  However, this period id is not guaranteed to
1025correspond to the desired period.  The period id is used to
1026access this period in other rate monotonic manager directives.
1027
1028@subheading NOTES:
1029
1030This directive will not cause the running task to be
1031preempted.
1032
1033@c
1034@c
1035@c
1036@page
1037@subsection RATE_MONOTONIC_CANCEL - Cancel a period
1038
1039@cindex cancel a period
1040
1041@subheading CALLING SEQUENCE:
1042
1043@ifset is-C
1044@findex rtems_rate_monotonic_cancel
1045@example
1046rtems_status_code rtems_rate_monotonic_cancel(
1047  rtems_id id
1048);
1049@end example
1050@end ifset
1051
1052@ifset is-Ada
1053@example
1054procedure Rate_Monotonic_Cancel (
1055   ID     : in     RTEMS.ID;
1056   Result :    out RTEMS.Status_Codes
1057);
1058@end example
1059@end ifset
1060
1061@subheading DIRECTIVE STATUS CODES:
1062@code{@value{RPREFIX}SUCCESSFUL} - period canceled successfully@*
1063@code{@value{RPREFIX}INVALID_ID} - invalid rate monotonic period id@*
1064@code{@value{RPREFIX}NOT_OWNER_OF_RESOURCE} - rate monotonic period not created by calling task
1065
1066@subheading DESCRIPTION:
1067
1068This directive cancels the rate monotonic period id.
1069This period will be reinitiated by the next invocation of
1070@code{@value{DIRPREFIX}rate_monotonic_period} with id.
1071
1072@subheading NOTES:
1073
1074This directive will not cause the running task to be
1075preempted.
1076
1077The rate monotonic period specified by id must have
1078been created by the calling task.
1079
1080@c
1081@c
1082@c
1083@page
1084@subsection RATE_MONOTONIC_DELETE - Delete a rate monotonic period
1085
1086@cindex delete a period
1087
1088@subheading CALLING SEQUENCE:
1089
1090@ifset is-C
1091@findex rtems_rate_monotonic_delete
1092@example
1093rtems_status_code rtems_rate_monotonic_delete(
1094  rtems_id id
1095);
1096@end example
1097@end ifset
1098
1099@ifset is-Ada
1100@example
1101procedure Rate_Monotonic_Delete (
1102   ID     : in     RTEMS.ID;
1103   Result :    out RTEMS.Status_Codes
1104);
1105@end example
1106@end ifset
1107
1108@subheading DIRECTIVE STATUS CODES:
1109@code{@value{RPREFIX}SUCCESSFUL} - period deleted successfully@*
1110@code{@value{RPREFIX}INVALID_ID} - invalid rate monotonic period id
1111
1112@subheading DESCRIPTION:
1113
1114This directive deletes the rate monotonic period
1115specified by id.  If the period is running, it is automatically
1116canceled.  The PCB for the deleted period is reclaimed by RTEMS.
1117
1118@subheading NOTES:
1119
1120This directive will not cause the running task to be
1121preempted.
1122
1123A rate monotonic period can be deleted by a task
1124other than the task which created the period.
1125
1126@c
1127@c
1128@c
1129@page
1130@subsection RATE_MONOTONIC_PERIOD - Conclude current/Start next period
1131
1132@cindex conclude current period
1133@cindex start current period
1134@cindex period initiation
1135
1136@subheading CALLING SEQUENCE:
1137
1138@ifset is-C
1139@findex rtems_rate_monotonic_period
1140@example
1141rtems_status_code rtems_rate_monotonic_period(
1142  rtems_id       id,
1143  rtems_interval length
1144);
1145@end example
1146@end ifset
1147
1148@ifset is-Ada
1149@example
1150procedure Rate_Monotonic_Period (
1151   ID      : in     RTEMS.ID;
1152   Length  : in     RTEMS.Interval;
1153   Result  :    out RTEMS.Status_Codes
1154);
1155@end example
1156@end ifset
1157
1158@subheading DIRECTIVE STATUS CODES:
1159@code{@value{RPREFIX}SUCCESSFUL} - period initiated successfully@*
1160@code{@value{RPREFIX}INVALID_ID} - invalid rate monotonic period id@*
1161@code{@value{RPREFIX}NOT_OWNER_OF_RESOURCE} - period not created by calling task@*
1162@code{@value{RPREFIX}NOT_DEFINED} - period has never been initiated (only
1163possible when period is set to PERIOD_STATUS)@*
1164@code{@value{RPREFIX}TIMEOUT} - period has expired
1165
1166@subheading DESCRIPTION:
1167
1168This directive initiates the rate monotonic period id
1169with a length of period ticks.  If id is running, then the
1170calling task will block for the remainder of the period before
1171reinitiating the period with the specified period.  If id was
1172not running (either expired or never initiated), the period is
1173immediately initiated and the directive returns immediately.
1174
1175If invoked with a period of @code{@value{RPREFIX}PERIOD_STATUS} ticks, the
1176current state of id will be returned.  The directive status
1177indicates the current state of the period.  This does not alter
1178the state or period of the period.
1179
1180@subheading NOTES:
1181
1182This directive will not cause the running task to be preempted.
1183
1184@c
1185@c
1186@c
1187@page
1188@subsection RATE_MONOTONIC_GET_STATUS - Obtain status from a period
1189
1190@cindex get status of period
1191@cindex obtain status of period
1192
1193@subheading CALLING SEQUENCE:
1194
1195@ifset is-C
1196@findex rtems_rate_monotonic_get_status
1197@example
1198rtems_status_code rtems_rate_monotonic_get_status(
1199  rtems_id                            id,
1200  rtems_rate_monotonic_period_status *status
1201);
1202@end example
1203@end ifset
1204
1205@ifset is-Ada
1206@example
1207procedure Rate_Monotonic_Get_Status (
1208   ID      : in     RTEMS.ID;
1209   Status  :    out RTEMS.Rate_Monotonic_Period_Status;
1210   Result  :    out RTEMS.Status_Codes
1211);
1212@end example
1213@end ifset
1214
1215@subheading DIRECTIVE STATUS CODES:
1216@code{@value{RPREFIX}SUCCESSFUL} - period initiated successfully@*
1217@code{@value{RPREFIX}INVALID_ID} - invalid rate monotonic period id@*
1218@code{@value{RPREFIX}INVALID_ADDRESS} - invalid address of status@*
1219
1220@subheading DESCRIPTION:
1221
1222This directive returns status information associated with
1223the rate monotonic period id in the following data @value{STRUCTURE}:
1224
1225@ifset is-C
1226@findex rtems_rate_monotonic_period_status
1227@example
1228typedef struct @{
1229  rtems_rate_monotonic_period_states  state;
1230  rtems_unsigned32                    ticks_since_last_period;
1231  rtems_unsigned32                    ticks_executed_since_last_period;
1232@}  rtems_rate_monotonic_period_status;
1233@end example
1234@end ifset
1235
1236@ifset is-Ada
1237@example
1238type Rate_Monotonic_Period_Status is
1239   begin
1240      State                            : RTEMS.Rate_Monotonic_Period_States;
1241      Ticks_Since_Last_Period          : RTEMS.Unsigned32;
1242      Ticks_Executed_Since_Last_Period : RTEMS.Unsigned32;
1243   end record;
1244@end example
1245@end ifset
1246
1247@c RATE_MONOTONIC_INACTIVE does not have RTEMS_ in front of it.
1248
1249If the period's state is @code{RATE_MONOTONIC_INACTIVE}, both
1250ticks_since_last_period and ticks_executed_since_last_period
1251will be set to 0.  Otherwise, ticks_since_last_period will
1252contain the number of clock ticks which have occurred since
1253the last invocation of the
1254@code{@value{DIRPREFIX}rate_monotonic_period} directive.
1255Also in this case, the ticks_executed_since_last_period will indicate
1256how much processor time the owning task has consumed since the invocation
1257of the @code{@value{DIRPREFIX}rate_monotonic_period} directive.
1258
1259@subheading NOTES:
1260
1261This directive will not cause the running task to be preempted.
1262
1263@c
1264@c
1265@c
1266@page
1267@subsection RATE_MONOTONIC_GET_STATISTICS - Obtain statistics from a period
1268
1269@cindex get statistics of period
1270@cindex obtain statistics of period
1271
1272@subheading CALLING SEQUENCE:
1273
1274@ifset is-C
1275@findex rtems_rate_monotonic_get_statistics
1276@example
1277rtems_status_code rtems_rate_monotonic_get_statistics(
1278  rtems_id                                id,
1279  rtems_rate_monotonic_period_statistics *statistics
1280);
1281@end example
1282@end ifset
1283
1284@ifset is-Ada
1285@example
1286NOT SUPPORTED FROM Ada BINDING
1287@end example
1288@end ifset
1289
1290@subheading DIRECTIVE STATUS CODES:
1291@code{@value{RPREFIX}SUCCESSFUL} - period initiated successfully@*
1292@code{@value{RPREFIX}INVALID_ID} - invalid rate monotonic period id@*
1293@code{@value{RPREFIX}INVALID_ADDRESS} - invalid address of statistics@*
1294
1295@subheading DESCRIPTION:
1296
1297This directive returns statistics information associated with
1298the rate monotonic period id in the following data @value{STRUCTURE}:
1299
1300@ifset is-C
1301@findex rtems_rate_monotonic_period_statistics
1302@example
1303typedef struct @{
1304 uint32_t     count;           /* periods executed */
1305 uint32_t     missed_count;    /* period deadlines missed */
1306 uint32_t     min_cpu_time;    /* minimum CPU time used in a period */
1307 uint32_t     max_cpu_time;    /* maximum CPU time used in a period */
1308 uint32_t     total_cpu_time;  /* total CPU time consumed */
1309 uint32_t     min_wall_time;   /* minimum wall time used in a period */
1310 uint32_t     max_wall_time;   /* maximum wall time used in a period */
1311 uint32_t     total_wall_time; /* total wall time consumed */
1312@}  rtems_rate_monotonic_period_statistics;
1313@end example
1314@end ifset
1315
1316@ifset is-Ada
1317@example
1318NOT SUPPORTED FROM Ada BINDING
1319@end example
1320@end ifset
1321
1322This directive returns the current statistics information for
1323the period instance assocaited with @code{id}.  The information
1324returned is indicated by the structure above.
1325
1326@subheading NOTES:
1327
1328This directive will not cause the running task to be preempted.
1329
1330@c
1331@c
1332@c
1333@page
1334@subsection RATE_MONOTONIC_RESET_STATISTICS - Reset statistics for a period
1335
1336@cindex reset statistics of period
1337
1338@subheading CALLING SEQUENCE:
1339
1340@ifset is-C
1341@findex rtems_rate_monotonic_reset_statistics
1342@example
1343rtems_status_code rtems_rate_monotonic_reset_statistics(
1344  rtems_id  id
1345);
1346@end example
1347@end ifset
1348
1349@ifset is-Ada
1350@example
1351procedure Rate_Monotonic_Reset_Statistics (
1352   ID     : in     RTEMS.ID;
1353   Result :    out RTEMS.Status_Codes
1354);
1355@end example
1356@end ifset
1357
1358@subheading DIRECTIVE STATUS CODES:
1359@code{@value{RPREFIX}SUCCESSFUL} - period initiated successfully@*
1360@code{@value{RPREFIX}INVALID_ID} - invalid rate monotonic period id@*
1361
1362@subheading DESCRIPTION:
1363
1364This directive resets the statistics information associated with
1365this rate monotonic period instance.
1366
1367@subheading NOTES:
1368
1369This directive will not cause the running task to be preempted.
1370
1371@c
1372@c
1373@c
1374@page
1375@subsection RATE_MONOTONIC_RESET_ALL_STATISTICS - Reset statistics for all periods
1376
1377@cindex reset statistics of all periods
1378
1379@subheading CALLING SEQUENCE:
1380
1381@ifset is-C
1382@findex rtems_rate_monotonic_reset_all_statistics
1383@example
1384void rtems_rate_monotonic_reset_all_statistics(void);
1385@end example
1386@end ifset
1387
1388@ifset is-Ada
1389@example
1390procedure Rate_Monotonic_Reset_All_Statistics;
1391@end example
1392@end ifset
1393
1394@subheading DIRECTIVE STATUS CODES:
1395
1396NONE
1397
1398@subheading DESCRIPTION:
1399
1400This directive resets the statistics information associated with
1401all rate monotonic period instances.
1402
1403@subheading NOTES:
1404
1405This directive will not cause the running task to be preempted.
1406
1407@c
1408@c
1409@c
1410@page
1411@subsection RATE_MONOTONIC_REPORT_STATISTICS - Print period statistics report
1412
1413@cindex print period statistics report
1414@cindex period statistics report
1415
1416@subheading CALLING SEQUENCE:
1417
1418@ifset is-C
1419@findex rtems_rate_monotonic_report_statistics
1420@example
1421void rtems_rate_monotonic_report_statistics(void);
1422@end example
1423@end ifset
1424
1425@ifset is-Ada
1426@example
1427procedure Rate_Monotonic_Report_Statistics;
1428@end example
1429@end ifset
1430
1431@subheading DIRECTIVE STATUS CODES:
1432
1433NONE
1434
1435@subheading DESCRIPTION:
1436
1437This directive prints a report on all active periods which have
1438executed at least one period. The following is an example of the
1439output generated by this directive.
1440
1441@ifset is-C
1442@findex rtems_rate_monotonic_period_statistics
1443@example
1444   ID      OWNER   PERIODS  MISSED    CPU TIME    WALL TIME
1445                                    MIN/MAX/AVG  MIN/MAX/AVG
14460x42010001  TA1       502     0       0/1/0.99    0/0/0.00
14470x42010002  TA2       502     0       0/1/0.99    0/0/0.00
14480x42010003  TA3       501     0       0/1/0.99    0/0/0.00
14490x42010004  TA4       501     0       0/1/0.99    0/0/0.00
14500x42010005  TA5        10     0       0/1/0.90    0/0/0.00
1451@end example
1452@end ifset
1453
1454@subheading NOTES:
1455
1456This directive will not cause the running task to be preempted.
Note: See TracBrowser for help on using the repository browser.