source: rtems/doc/user/rtmon.t @ a570a14

4.8
Last change on this file since a570a14 was a570a14, checked in by Joel Sherrill <joel.sherrill@…>, on Jul 15, 2008 at 9:49:59 PM

2008-07-15 Joel Sherrill <joel.sherrill@…>

  • user/barrier.t, user/clock.t, user/dpmem.t, user/msg.t, user/part.t, user/region.t, user/rtmon.t, user/sem.t, user/task.t, user/timer.t: Correct documentation typos noticed and thankfully reported by Fabrício de Novaes Kucinskis <fabricio@…>
  • Property mode set to 100644
File size: 47.7 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
828The above task creates a rate monotonic period as
829part of its initialization.  The first time the loop is
830executed, the @code{@value{DIRPREFIX}rate_monotonic_period}
831directive will initiate the period for 100 ticks and return
832immediately.  Subsequent invocations of the
833@code{@value{DIRPREFIX}rate_monotonic_period} directive will result
834in the task blocking for the remainder of the 100 tick period.
835If, for any reason, the body of the loop takes more than 100
836ticks to execute, the @code{@value{DIRPREFIX}rate_monotonic_period}
837directive will return the @code{@value{RPREFIX}TIMEOUT} status. 
838If the above task misses its deadline, it will delete the rate
839monotonic period and itself.
840
841@subsection Task with Multiple Periods
842
843This example consists of a single periodic task
844which, after initialization, performs two sets of actions every
845100 clock ticks.  The first set of actions is performed in the
846first forty clock ticks of every 100 clock ticks, while the
847second set of actions is performed between the fortieth and
848seventieth clock ticks.  The last thirty clock ticks are not
849used by this task.
850
851@page
852@example
853rtems_task Periodic_task(rtems_task_argument arg)
854@{
855  rtems_name        name_1, name_2;
856  rtems_id          period_1, period_2;
857  rtems_status_code status;
858
859  name_1 = rtems_build_name( 'P', 'E', 'R', '1' );
860  name_2 = rtems_build_name( 'P', 'E', 'R', '2' );
861
862  (void ) rtems_rate_monotonic_create( name_1, &period_1 );
863  (void ) rtems_rate_monotonic_create( name_2, &period_2 );
864
865  while ( 1 ) @{
866    if ( rtems_rate_monotonic_period( period_1, 100 ) == TIMEOUT )
867      break;
868
869    if ( rtems_rate_monotonic_period( period_2, 40 ) == TIMEOUT )
870      break;
871
872    /*
873     *  Perform first set of actions between clock
874     *  ticks 0 and 39 of every 100 ticks.
875     */
876
877    if ( rtems_rate_monotonic_period( period_2, 30 ) == TIMEOUT )
878      break;
879
880    /*
881     *  Perform second set of actions between clock 40 and 69
882     *  of every 100 ticks.  THEN ...
883     *
884     *  Check to make sure we didn't miss the period_2 period.
885     */
886
887    if ( rtems_rate_monotonic_period( period_2, STATUS ) == TIMEOUT )
888      break;
889
890    (void) rtems_rate_monotonic_cancel( period_2 );
891  @}
892
893  /* missed period so delete period and SELF */
894
895  (void ) rtems_rate_monotonic_delete( period_1 );
896  (void ) rtems_rate_monotonic_delete( period_2 );
897  (void ) task_delete( SELF );
898@}
899@end example
900
901The above task creates two rate monotonic periods as
902part of its initialization.  The first time the loop is
903executed, the @code{@value{DIRPREFIX}rate_monotonic_period}
904directive will initiate the period_1 period for 100 ticks
905and return immediately.  Subsequent invocations of the
906@code{@value{DIRPREFIX}rate_monotonic_period} directive
907for period_1 will result in the task blocking for the remainder
908of the 100 tick period.  The period_2 period is used to control
909the execution time of the two sets of actions within each 100
910tick period established by period_1.  The
911@code{@value{DIRPREFIX}rate_monotonic_cancel( period_2 )}
912call is performed to ensure that the period_2 period
913does not expire while the task is blocked on the period_1
914period.  If this cancel operation were not performed, every time
915the @code{@value{DIRPREFIX}rate_monotonic_period( period_2, 40 )}
916call is executed, except for the initial one, a directive status
917of @code{@value{RPREFIX}TIMEOUT} is returned.  It is important to
918note that every time this call is made, the period_2 period will be
919initiated immediately and the task will not block.
920
921If, for any reason, the task misses any deadline, the
922@code{@value{DIRPREFIX}rate_monotonic_period} directive will
923return the @code{@value{RPREFIX}TIMEOUT}
924directive status.  If the above task misses its deadline, it
925will delete the rate monotonic periods and itself.
926
927@section Directives
928
929This section details the rate monotonic manager's
930directives.  A subsection is dedicated to each of this manager's
931directives and describes the calling sequence, related
932constants, usage, and status codes.
933
934@c
935@c
936@c
937@page
938@subsection RATE_MONOTONIC_CREATE - Create a rate monotonic period
939
940@cindex create a period
941
942@subheading CALLING SEQUENCE:
943
944@ifset is-C
945@findex rtems_rate_monotonic_create
946@example
947rtems_status_code rtems_rate_monotonic_create(
948  rtems_name  name,
949  rtems_id   *id
950);
951@end example
952@end ifset
953
954@ifset is-Ada
955@example
956procedure Rate_Monotonic_Create (
957   Name   : in     RTEMS.Name;
958   ID     :    out RTEMS.ID;
959   Result :    out RTEMS.Status_Codes
960);
961@end example
962@end ifset
963
964@subheading DIRECTIVE STATUS CODES:
965@code{@value{RPREFIX}SUCCESSFUL} - rate monotonic period created successfully@*
966@code{@value{RPREFIX}INVALID_NAME} - invalid period name@*
967@code{@value{RPREFIX}TOO_MANY} - too many periods created
968
969@subheading DESCRIPTION:
970
971This directive creates a rate monotonic period.  The
972assigned rate monotonic id is returned in id.  This id is used
973to access the period with other rate monotonic manager
974directives.  For control and maintenance of the rate monotonic
975period, RTEMS allocates a PCB from the local PCB free pool and
976initializes it.
977
978@subheading NOTES:
979
980This directive will not cause the calling task to be
981preempted.
982
983@c
984@c
985@c
986@page
987@subsection RATE_MONOTONIC_IDENT - Get ID of a period
988
989@cindex get ID of a period
990@cindex obtain ID of a period
991
992@subheading CALLING SEQUENCE:
993
994@ifset is-C
995@findex rtems_rate_monotonic_ident
996@example
997rtems_status_code rtems_rate_monotonic_ident(
998  rtems_name  name,
999  rtems_id   *id
1000);
1001@end example
1002@end ifset
1003
1004@ifset is-Ada
1005@example
1006procedure Rate_Monotonic_Ident (
1007   Name   : in     RTEMS.Name;
1008   ID     :    out RTEMS.ID;
1009   Result :    out RTEMS.Status_Codes
1010);
1011@end example
1012@end ifset
1013
1014@subheading DIRECTIVE STATUS CODES:
1015@code{@value{RPREFIX}SUCCESSFUL} - period identified successfully@*
1016@code{@value{RPREFIX}INVALID_NAME} - period name not found
1017
1018@subheading DESCRIPTION:
1019
1020This directive obtains the period id associated with
1021the period name to be acquired.  If the period name is not
1022unique, then the period id will match one of the periods with
1023that name.  However, this period id is not guaranteed to
1024correspond to the desired period.  The period id is used to
1025access this period in other rate monotonic manager directives.
1026
1027@subheading NOTES:
1028
1029This directive will not cause the running task to be
1030preempted.
1031
1032@c
1033@c
1034@c
1035@page
1036@subsection RATE_MONOTONIC_CANCEL - Cancel a period
1037
1038@cindex cancel a period
1039
1040@subheading CALLING SEQUENCE:
1041
1042@ifset is-C
1043@findex rtems_rate_monotonic_cancel
1044@example
1045rtems_status_code rtems_rate_monotonic_cancel(
1046  rtems_id id
1047);
1048@end example
1049@end ifset
1050
1051@ifset is-Ada
1052@example
1053procedure Rate_Monotonic_Cancel (
1054   ID     : in     RTEMS.ID;
1055   Result :    out RTEMS.Status_Codes
1056);
1057@end example
1058@end ifset
1059
1060@subheading DIRECTIVE STATUS CODES:
1061@code{@value{RPREFIX}SUCCESSFUL} - period canceled successfully@*
1062@code{@value{RPREFIX}INVALID_ID} - invalid rate monotonic period id@*
1063@code{@value{RPREFIX}NOT_OWNER_OF_RESOURCE} - rate monotonic period not created by calling task
1064
1065@subheading DESCRIPTION:
1066
1067This directive cancels the rate monotonic period id.
1068This period will be reinitiated by the next invocation of
1069@code{@value{DIRPREFIX}rate_monotonic_period} with id.
1070
1071@subheading NOTES:
1072
1073This directive will not cause the running task to be
1074preempted.
1075
1076The rate monotonic period specified by id must have
1077been created by the calling task.
1078
1079@c
1080@c
1081@c
1082@page
1083@subsection RATE_MONOTONIC_DELETE - Delete a rate monotonic period
1084
1085@cindex delete a period
1086
1087@subheading CALLING SEQUENCE:
1088
1089@ifset is-C
1090@findex rtems_rate_monotonic_delete
1091@example
1092rtems_status_code rtems_rate_monotonic_delete(
1093  rtems_id id
1094);
1095@end example
1096@end ifset
1097
1098@ifset is-Ada
1099@example
1100procedure Rate_Monotonic_Delete (
1101   ID     : in     RTEMS.ID;
1102   Result :    out RTEMS.Status_Codes
1103);
1104@end example
1105@end ifset
1106
1107@subheading DIRECTIVE STATUS CODES:
1108@code{@value{RPREFIX}SUCCESSFUL} - period deleted successfully@*
1109@code{@value{RPREFIX}INVALID_ID} - invalid rate monotonic period id
1110
1111@subheading DESCRIPTION:
1112
1113This directive deletes the rate monotonic period
1114specified by id.  If the period is running, it is automatically
1115canceled.  The PCB for the deleted period is reclaimed by RTEMS.
1116
1117@subheading NOTES:
1118
1119This directive will not cause the running task to be
1120preempted.
1121
1122A rate monotonic period can be deleted by a task
1123other than the task which created the period.
1124
1125@c
1126@c
1127@c
1128@page
1129@subsection RATE_MONOTONIC_PERIOD - Conclude current/Start next period
1130
1131@cindex conclude current period
1132@cindex start current period
1133@cindex period initiation
1134
1135@subheading CALLING SEQUENCE:
1136
1137@ifset is-C
1138@findex rtems_rate_monotonic_period
1139@example
1140rtems_status_code rtems_rate_monotonic_period(
1141  rtems_id       id,
1142  rtems_interval length
1143);
1144@end example
1145@end ifset
1146
1147@ifset is-Ada
1148@example
1149procedure Rate_Monotonic_Period (
1150   ID      : in     RTEMS.ID;
1151   Length  : in     RTEMS.Interval;
1152   Result  :    out RTEMS.Status_Codes
1153);
1154@end example
1155@end ifset
1156
1157@subheading DIRECTIVE STATUS CODES:
1158@code{@value{RPREFIX}SUCCESSFUL} - period initiated successfully@*
1159@code{@value{RPREFIX}INVALID_ID} - invalid rate monotonic period id@*
1160@code{@value{RPREFIX}NOT_OWNER_OF_RESOURCE} - period not created by calling task@*
1161@code{@value{RPREFIX}NOT_DEFINED} - period has never been initiated (only
1162possible when period is set to PERIOD_STATUS)@*
1163@code{@value{RPREFIX}TIMEOUT} - period has expired
1164
1165@subheading DESCRIPTION:
1166
1167This directive initiates the rate monotonic period id
1168with a length of period ticks.  If id is running, then the
1169calling task will block for the remainder of the period before
1170reinitiating the period with the specified period.  If id was
1171not running (either expired or never initiated), the period is
1172immediately initiated and the directive returns immediately.
1173
1174If invoked with a period of @code{@value{RPREFIX}PERIOD_STATUS} ticks, the
1175current state of id will be returned.  The directive status
1176indicates the current state of the period.  This does not alter
1177the state or period of the period.
1178
1179@subheading NOTES:
1180
1181This directive will not cause the running task to be preempted.
1182
1183@c
1184@c
1185@c
1186@page
1187@subsection RATE_MONOTONIC_GET_STATUS - Obtain status from a period
1188
1189@cindex get status of period
1190@cindex obtain status of period
1191
1192@subheading CALLING SEQUENCE:
1193
1194@ifset is-C
1195@findex rtems_rate_monotonic_get_status
1196@example
1197rtems_status_code rtems_rate_monotonic_get_status(
1198  rtems_id                            id,
1199  rtems_rate_monotonic_period_status *status
1200);
1201@end example
1202@end ifset
1203
1204@ifset is-Ada
1205@example
1206procedure Rate_Monotonic_Get_Status (
1207   ID      : in     RTEMS.ID;
1208   Status  :    out RTEMS.Rate_Monotonic_Period_Status;
1209   Result  :    out RTEMS.Status_Codes
1210);
1211@end example
1212@end ifset
1213
1214@subheading DIRECTIVE STATUS CODES:
1215@code{@value{RPREFIX}SUCCESSFUL} - period initiated successfully@*
1216@code{@value{RPREFIX}INVALID_ID} - invalid rate monotonic period id@*
1217@code{@value{RPREFIX}INVALID_ADDRESS} - invalid address of status@*
1218
1219@subheading DESCRIPTION:
1220
1221This directive returns status information associated with
1222the rate monotonic period id in the following data @value{STRUCTURE}:
1223
1224@ifset is-C
1225@findex rtems_rate_monotonic_period_status
1226@example
1227typedef struct @{
1228  rtems_id                            owner;
1229  rtems_rate_monotonic_period_states  state;
1230  #ifdef RTEMS_ENABLE_NANOSECOND_RATE_MONOTONIC_STATISTICS
1231    struct timespec                   since_last_period;
1232  #else
1233    uint32_t                          ticks_since_last_period;
1234  #endif
1235  #ifdef RTEMS_ENABLE_NANOSECOND_CPU_USAGE_STATISTICS
1236    struct timespec                   executed_since_last_period;
1237  #else
1238    uint32_t                          ticks_executed_since_last_period;
1239  #endif
1240@}  rtems_rate_monotonic_period_status;
1241@end example
1242@end ifset
1243
1244@ifset is-Ada
1245@example
1246type Rate_Monotonic_Period_Status is
1247   begin
1248      Owner                            : RTEMS.ID;
1249      State                            : RTEMS.Rate_Monotonic_Period_States;
1250      Ticks_Since_Last_Period          : RTEMS.Unsigned32;
1251      Ticks_Executed_Since_Last_Period : RTEMS.Unsigned32;
1252   end record;
1253@end example
1254@end ifset
1255
1256@c RATE_MONOTONIC_INACTIVE does not have RTEMS_ in front of it.
1257
1258A configure time option can be used to select whether the time information is
1259given in ticks or seconds and nanoseconds.  The default is seconds and
1260nanoseconds.  If the period's state is @code{RATE_MONOTONIC_INACTIVE}, both
1261time values will be set to 0.  Otherwise, both time values will contain
1262time information since the last invocation of the
1263@code{@value{DIRPREFIX}rate_monotonic_period} directive.  More
1264specifically, the (ticks_)since_last_period value contains the elapsed time
1265which has occurred since the last invocation of the
1266@code{@value{DIRPREFIX}rate_monotonic_period} directive and the
1267(ticks_)executed_since_last_period contains how much processor time the
1268owning task has consumed since the invocation of the
1269@code{@value{DIRPREFIX}rate_monotonic_period} directive.
1270
1271@subheading NOTES:
1272
1273This directive will not cause the running task to be preempted.
1274
1275@c
1276@c
1277@c
1278@page
1279@subsection RATE_MONOTONIC_GET_STATISTICS - Obtain statistics from a period
1280
1281@cindex get statistics of period
1282@cindex obtain statistics of period
1283
1284@subheading CALLING SEQUENCE:
1285
1286@ifset is-C
1287@findex rtems_rate_monotonic_get_statistics
1288@example
1289rtems_status_code rtems_rate_monotonic_get_statistics(
1290  rtems_id                                id,
1291  rtems_rate_monotonic_period_statistics *statistics
1292);
1293@end example
1294@end ifset
1295
1296@ifset is-Ada
1297@example
1298NOT SUPPORTED FROM Ada BINDING
1299@end example
1300@end ifset
1301
1302@subheading DIRECTIVE STATUS CODES:
1303@code{@value{RPREFIX}SUCCESSFUL} - period initiated successfully@*
1304@code{@value{RPREFIX}INVALID_ID} - invalid rate monotonic period id@*
1305@code{@value{RPREFIX}INVALID_ADDRESS} - invalid address of statistics@*
1306
1307@subheading DESCRIPTION:
1308
1309This directive returns statistics information associated with
1310the rate monotonic period id in the following data @value{STRUCTURE}:
1311
1312@ifset is-C
1313@findex rtems_rate_monotonic_period_statistics
1314@example
1315typedef struct @{
1316  uint32_t     count;
1317  uint32_t     missed_count;
1318  #ifdef RTEMS_ENABLE_NANOSECOND_CPU_USAGE_STATISTICS
1319    struct timespec min_cpu_time;
1320    struct timespec max_cpu_time;
1321    struct timespec total_cpu_time;
1322  #else
1323    uint32_t  min_cpu_time;
1324    uint32_t  max_cpu_time;
1325    uint32_t  total_cpu_time;
1326  #endif
1327  #ifdef RTEMS_ENABLE_NANOSECOND_RATE_MONOTONIC_STATISTICS
1328    struct timespec min_wall_time;
1329    struct timespec max_wall_time;
1330    struct timespec total_wall_time;
1331  #else
1332    uint32_t  min_wall_time;
1333    uint32_t  max_wall_time;
1334    uint32_t  total_wall_time;
1335  #endif
1336@}  rtems_rate_monotonic_period_statistics;
1337@end example
1338@end ifset
1339
1340@ifset is-Ada
1341@example
1342NOT SUPPORTED FROM Ada BINDING
1343@end example
1344@end ifset
1345
1346This directive returns the current statistics information for
1347the period instance assocaited with @code{id}.  The information
1348returned is indicated by the structure above.
1349
1350@subheading NOTES:
1351
1352This directive will not cause the running task to be preempted.
1353
1354@c
1355@c
1356@c
1357@page
1358@subsection RATE_MONOTONIC_RESET_STATISTICS - Reset statistics for a period
1359
1360@cindex reset statistics of period
1361
1362@subheading CALLING SEQUENCE:
1363
1364@ifset is-C
1365@findex rtems_rate_monotonic_reset_statistics
1366@example
1367rtems_status_code rtems_rate_monotonic_reset_statistics(
1368  rtems_id  id
1369);
1370@end example
1371@end ifset
1372
1373@ifset is-Ada
1374@example
1375procedure Rate_Monotonic_Reset_Statistics (
1376   ID     : in     RTEMS.ID;
1377   Result :    out RTEMS.Status_Codes
1378);
1379@end example
1380@end ifset
1381
1382@subheading DIRECTIVE STATUS CODES:
1383@code{@value{RPREFIX}SUCCESSFUL} - period initiated successfully@*
1384@code{@value{RPREFIX}INVALID_ID} - invalid rate monotonic period id@*
1385
1386@subheading DESCRIPTION:
1387
1388This directive resets the statistics information associated with
1389this rate monotonic period instance.
1390
1391@subheading NOTES:
1392
1393This directive will not cause the running task to be preempted.
1394
1395@c
1396@c
1397@c
1398@page
1399@subsection RATE_MONOTONIC_RESET_ALL_STATISTICS - Reset statistics for all periods
1400
1401@cindex reset statistics of all periods
1402
1403@subheading CALLING SEQUENCE:
1404
1405@ifset is-C
1406@findex rtems_rate_monotonic_reset_all_statistics
1407@example
1408void rtems_rate_monotonic_reset_all_statistics(void);
1409@end example
1410@end ifset
1411
1412@ifset is-Ada
1413@example
1414procedure Rate_Monotonic_Reset_All_Statistics;
1415@end example
1416@end ifset
1417
1418@subheading DIRECTIVE STATUS CODES:
1419
1420NONE
1421
1422@subheading DESCRIPTION:
1423
1424This directive resets the statistics information associated with
1425all rate monotonic period instances.
1426
1427@subheading NOTES:
1428
1429This directive will not cause the running task to be preempted.
1430
1431@c
1432@c
1433@c
1434@page
1435@subsection RATE_MONOTONIC_REPORT_STATISTICS - Print period statistics report
1436
1437@cindex print period statistics report
1438@cindex period statistics report
1439
1440@subheading CALLING SEQUENCE:
1441
1442@ifset is-C
1443@findex rtems_rate_monotonic_report_statistics
1444@example
1445void rtems_rate_monotonic_report_statistics(void);
1446@end example
1447@end ifset
1448
1449@ifset is-Ada
1450@example
1451procedure Rate_Monotonic_Report_Statistics;
1452@end example
1453@end ifset
1454
1455@subheading DIRECTIVE STATUS CODES:
1456
1457NONE
1458
1459@subheading DESCRIPTION:
1460
1461This directive prints a report on all active periods which have
1462executed at least one period. The following is an example of the
1463output generated by this directive.
1464
1465@ifset is-C
1466@findex rtems_rate_monotonic_period_statistics
1467@example
1468   ID      OWNER   PERIODS  MISSED    CPU TIME    WALL TIME
1469                                    MIN/MAX/AVG  MIN/MAX/AVG
14700x42010001  TA1       502     0       0/1/0.99    0/0/0.00
14710x42010002  TA2       502     0       0/1/0.99    0/0/0.00
14720x42010003  TA3       501     0       0/1/0.99    0/0/0.00
14730x42010004  TA4       501     0       0/1/0.99    0/0/0.00
14740x42010005  TA5        10     0       0/1/0.90    0/0/0.00
1475@end example
1476@end ifset
1477
1478@subheading NOTES:
1479
1480This directive will not cause the running task to be preempted.
Note: See TracBrowser for help on using the repository browser.