source: rtems/doc/user/rtmon.t @ 87ed029

4.104.114.84.95
Last change on this file since 87ed029 was 87ed029, checked in by Joel Sherrill <joel.sherrill@…>, on 04/02/98 at 16:18:26

Added "findex" for all directive pages but it turns out that this
blows up both makeinfo and texi2dvi. So I have commented them out.

  • Property mode set to 100644
File size: 38.0 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-1998.
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5@c
6@c  $Id$
7@c
8
9@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@section Introduction
18
19The rate monotonic manager provides facilities to
20implement tasks which execute in a periodic fashion.  The
21directives provided by the rate monotonic manager are:
22
23@itemize @bullet
24@item @code{@value{DIRPREFIX}rate_monotonic_create} - Create a rate monotonic period
25@item @code{@value{DIRPREFIX}rate_monotonic_ident} - Get ID of a period
26@item @code{@value{DIRPREFIX}rate_monotonic_cancel} - Cancel a period
27@item @code{@value{DIRPREFIX}rate_monotonic_delete} - Delete a rate monotonic period
28@item @code{@value{DIRPREFIX}rate_monotonic_period} - Conclude current/Start next period
29@item @code{@value{DIRPREFIX}rate_monotonic_get_status} - Obtain status information on period
30@end itemize
31
32@section Background
33
34The rate monotonic manager provides facilities to
35manage the execution of periodic tasks.  This manager was
36designed to support application designers who utilize the Rate
37Monotonic Scheduling Algorithm (RMS) to insure that their
38periodic tasks will meet their deadlines, even under transient
39overload conditions.  Although designed for hard real-time
40systems, the services provided by the rate monotonic manager may
41be used by any application which requires periodic tasks.
42
43@subsection Rate Monotonic Manager Required Support
44
45A clock tick is required to support the functionality provided by this manager.
46
47@subsection Rate Monotonic Manager Definitions
48
49A periodic task is one which must be executed at a
50regular interval.  The interval between successive iterations of
51the task is referred to as its period.  Periodic tasks can be
52characterized by the length of their period and execution time.
53The period and execution time of a task can be used to determine
54the processor utilization for that task.  Processor utilization
55is the percentage of processor time used and can be calculated
56on a per-task or system-wide basis.  Typically, the task's
57worst-case execution time will be less than its period.  For
58example, a periodic task's requirements may state that it should
59execute for 10 milliseconds every 100 milliseconds.  Although
60the execution time may be the average, worst, or best case, the
61worst-case execution time is more appropriate for use when
62analyzing system behavior under transient overload conditions.
63
64In contrast, an aperiodic task executes at irregular
65intervals and has only a soft deadline.  In other words, the
66deadlines for aperiodic tasks are not rigid, but adequate
67response times are desirable.  For example, an aperiodic task
68may process user input from a terminal.
69
70Finally, a sporadic task is an aperiodic task with a
71hard deadline and minimum interarrival time.  The minimum
72interarrival time is the minimum period of time which exists
73between successive iterations of the task.  For example, a
74sporadic task could be used to process the pressing of a fire
75button on a joystick.  The mechanical action of the fire button
76insures a minimum time period between successive activations,
77but the missile must be launched by a hard deadline.
78
79@subsection Rate Monotonic Scheduling Algorithm
80
81The Rate Monotonic Scheduling Algorithm (RMS) is
82important to real-time systems designers because it allows one
83to guarantee that a set of tasks is schedulable.  A set of tasks
84is said to be schedulable if all of the tasks can meet their
85deadlines.  RMS provides a set of rules which can be used to
86perform a guaranteed schedulability analysis for a task set.
87This analysis determines whether a task set is schedulable under
88worst-case conditions and emphasizes the predictability of the
89system's behavior.  It has been proven that:
90
91@itemize @code{ }
92@b{RMS is an optimal static priority algorithm for
93scheduling independent, preemptible, periodic tasks
94on a single processor.}
95@end itemize
96
97RMS is optimal in the sense that if a set of tasks
98can be scheduled by any static priority algorithm, then RMS will
99be able to schedule that task set.  RMS bases it schedulability
100analysis on the processor utilization level below which all
101deadlines can be met.
102
103RMS calls for the static assignment of task
104priorities based upon their period.  The shorter a task's
105period, the higher its priority.  For example, a task with a 1
106millisecond period has higher priority than a task with a 100
107millisecond period.  If two tasks have the same period, than RMS
108does not distinguish between the tasks.  However, RTEMS
109specifies that when given tasks of equal priority, the task
110which has been ready longest will execute first.  RMS's priority
111assignment scheme does not provide one with exact numeric values
112for task priorities.  For example, consider the following task
113set and priority assignments:
114
115@ifset use-ascii
116@example
117@group
118+--------------------+---------------------+---------------------+
119|        Task        |       Period        |      Priority       |
120|                    |  (in milliseconds)  |                     |
121+--------------------+---------------------+---------------------+
122|         1          |         100         |         Low         |
123+--------------------+---------------------+---------------------+
124|         2          |          50         |       Medium        |
125+--------------------+---------------------+---------------------+
126|         3          |          50         |       Medium        |
127+--------------------+---------------------+---------------------+
128|         4          |          25         |        High         |
129+--------------------+---------------------+---------------------+
130@end group
131@end example
132@end ifset
133
134@ifset use-tex
135@sp 1
136@tex
137\centerline{\vbox{\offinterlineskip\halign{
138\vrule\strut#&
139\hbox to 0.75in{\enskip\hfil#\hfil}&
140\vrule#&
141\hbox to 1.25in{\enskip\hfil#\hfil}&
142\vrule#&
143\hbox to 1.25in{\enskip\hfil#\hfil}&
144\vrule#\cr\noalign{\hrule}
145&\bf Task&& \bf Period && \bf Priority &\cr
146& && \bf (in milliseconds) && &\cr\noalign{\hrule}
147& 1 && 100 && Low &\cr\noalign{\hrule}
148& 2 && 50 && Medium &\cr\noalign{\hrule}
149& 3 && 50 && Medium &\cr\noalign{\hrule}
150& 4 && 25 && High &\cr\noalign{\hrule}
151}}\hfil}
152@end tex
153@end ifset
154
155@ifset use-html
156@html
157<CENTER>
158  <TABLE COLS=3 WIDTH="80%" BORDER=2>
159<TR><TD ALIGN=center><STRONG>Task</STRONG></TD>
160    <TD ALIGN=center><STRONG>Period (in milliseconds)</STRONG></TD>
161    <TD ALIGN=center><STRONG>Priority</STRONG></TD></TR>
162<TR><TD ALIGN=center>1</TD>
163    <TD ALIGN=center>100 </TD>
164    <TD ALIGN=center>Low</TD></TR>
165<TR><TD ALIGN=center>2</TD>
166    <TD ALIGN=center>50 </TD>
167    <TD ALIGN=center>Medium</TD></TR>
168<TR><TD ALIGN=center>3</TD>
169    <TD ALIGN=center>50 </TD>
170    <TD ALIGN=center>Medium</TD></TR>
171<TR><TD ALIGN=center>4</TD>
172    <TD ALIGN=center>25 </TD>
173    <TD ALIGN=center>High</TD></TR>
174  </TABLE>
175</CENTER>
176@end html
177@end ifset
178
179RMS only calls for task 1 to have the lowest
180priority, task 4 to have the highest priority, and tasks 2 and 3
181to have an equal priority between that of tasks 1 and 4.  The
182actual RTEMS priorities assigned to the tasks must only adhere
183to those guidelines.
184
185Many applications have tasks with both hard and soft
186deadlines.  The tasks with hard deadlines are typically referred
187to as the critical task set, with the soft deadline tasks being
188the non-critical task set.  The critical task set can be
189scheduled using RMS, with the non-critical tasks not executing
190under transient overload, by simply assigning priorities such
191that the lowest priority critical task (i.e. longest period) has
192a higher priority than the highest priority non-critical task.
193Although RMS may be used to assign priorities to the
194non-critical tasks, it is not necessary.  In this instance,
195schedulability is only guaranteed for the critical task set.
196
197@subsection Schedulability Analysis
198
199RMS allows application designers to insure that tasks
200can meet all deadlines, even under transient overload, without
201knowing exactly when any given task will execute by applying
202proven schedulability analysis rules.
203
204@lowersections
205
206@subsection Assumptions
207
208The schedulability analysis rules for RMS were
209developed based on the following assumptions:
210
211
212@itemize @bullet
213@item The requests for all tasks for which hard deadlines
214exist are periodic, with a constant interval between requests.
215
216@item Each task must complete before the next request for it
217occurs.
218
219@item The tasks are independent in that a task does not depend
220on the initiation or completion of requests for other tasks.
221
222@item The execution time for each task without preemption or
223interruption is constant and does not vary.
224
225@item Any non-periodic tasks in the system are special.  These
226tasks displace periodic tasks while executing and do not have
227hard, critical deadlines.
228@end itemize
229
230Once the basic schedulability analysis is understood,
231some of the above assumptions can be relaxed and the
232side-effects accounted for.
233
234@subsection Processor Utilization Rule
235
236The Processor Utilization Rule requires that
237processor utilization be calculated based upon the period and
238execution time of each task.  The fraction of processor time
239spent executing task index is Time(index) / Period(index).  The
240processor utilization can be calculated as follows:
241
242@example
243@group
244Utilization = 0
245
246for index = 1 to maximum_tasks
247  Utilization = Utilization + (Time(index)/Period(index))
248@end group
249@end example
250
251To insure schedulability even under transient
252overload, the processor utilization must adhere to the following
253rule:
254
255@example
256Utilization = maximum_tasks * (2(1/maximum_tasks) - 1)
257@end example
258
259As the number of tasks increases, the above formula
260approaches ln(2) for a worst-case utilization factor of
261approximately 0.693.  Many tasks sets can be scheduled with a
262greater utilization factor.  In fact, the average processor
263utilization threshold for a randomly generated task set is
264approximately 0.88.
265
266@subsection Processor Utilization Rule Example
267
268This example illustrates the application of the
269Processor Utilization Rule to an application with three critical
270periodic tasks.  The following table details the RMS priority,
271period, execution time, and processor utilization for each task:
272
273@ifset use-ascii
274@example
275@group
276    +------------+----------+--------+-----------+-------------+
277    |    Task    |   RMS    | Period | Execution |  Processor  |
278    |            | Priority |        |   Time    | Utilization |
279    +------------+----------+--------+-----------+-------------+
280    |     1      |   High   |  100   |    15     |    0.15     |
281    +------------+----------+--------+-----------+-------------+
282    |     2      |  Medium  |  200   |    50     |    0.25     |
283    +------------+----------+--------+-----------+-------------+
284    |     3      |   Low    |  300   |   100     |    0.33     |
285    +------------+----------+--------+-----------+-------------+
286@end group
287@end example
288@end ifset
289
290@ifset use-tex
291@sp 1
292@tex
293\centerline{\vbox{\offinterlineskip\halign{
294\vrule\strut#&
295\hbox to 0.75in{\enskip\hfil#\hfil}&
296\vrule#&
297\hbox to 0.75in{\enskip\hfil#\hfil}&
298\vrule#&
299\hbox to 0.75in{\enskip\hfil#\hfil}&
300\vrule#&
301\hbox to 1.00in{\enskip\hfil#\hfil}&
302\vrule#&
303\hbox to 1.00in{\enskip\hfil#\hfil}&
304\vrule#\cr\noalign{\hrule}
305&\bf Task&& \bf RMS && \bf Period && \bf Execution &&\bf Processor&\cr
306& && \bf Priority && &&\bf Time &&\bf Utilization &\cr\noalign{\hrule}
307& 1 && High && 100 && 15 && 0.15 &\cr\noalign{\hrule}
308& 2 && Medium && 200 && 50 && 0.25 &\cr\noalign{\hrule}
309& 3 && Low && 300 && 100 && 0.33 &\cr\noalign{\hrule}
310}}\hfil}
311@end tex
312@end ifset
313 
314@ifset use-html
315@html
316<CENTER>
317  <TABLE COLS=5 WIDTH="80%" BORDER=2>
318<TR><TD ALIGN=center><STRONG>Task</STRONG></TD>
319    <TD ALIGN=center><STRONG>RMS Priority</STRONG></TD>
320    <TD ALIGN=center><STRONG>Period</STRONG></TD>
321    <TD ALIGN=center><STRONG>Execution Time</STRONG></TD>
322    <TD ALIGN=center><STRONG>Processor Utilization</STRONG></TD></TR>
323<TR><TD ALIGN=center>1</TD>
324    <TD ALIGN=center>High</TD>
325    <TD ALIGN=center>100</TD>
326    <TD ALIGN=center>15</TD>
327    <TD ALIGN=center>0.15</TD></TR>
328<TR><TD ALIGN=center>2</TD>
329    <TD ALIGN=center>Medium</TD>
330    <TD ALIGN=center>200</TD>
331    <TD ALIGN=center>50</TD>
332    <TD ALIGN=center>0.25</TD></TR>
333<TR><TD ALIGN=center>3</TD>
334    <TD ALIGN=center>Low</TD>
335    <TD ALIGN=center>300</TD>
336    <TD ALIGN=center>100</TD>
337    <TD ALIGN=center>0.33</TD></TR>
338  </TABLE>
339</CENTER>
340@end html
341@end ifset
342
343The total processor utilization for this task set is
3440.73 which is below the upper bound of 3 * (2(1/3) - 1), or
3450.779, imposed by the Processor Utilization Rule.  Therefore,
346this task set is guaranteed to be schedulable using RMS.
347
348@subsection First Deadline Rule
349
350If a given set of tasks do exceed the processor
351utilization upper limit imposed by the Processor Utilization
352Rule, they can still be guaranteed to meet all their deadlines
353by application of the First Deadline Rule.  This rule can be
354stated as follows:
355
356For a given set of independent periodic tasks, if
357each task meets its first deadline when all tasks are started at
358the same time, then the deadlines will always be met for any
359combination of start times.
360
361A key point with this rule is that ALL periodic tasks
362are assumed to start at the exact same instant in time.
363Although this assumption may seem to be invalid,  RTEMS makes it
364quite easy to insure.  By having a non-preemptible user
365initialization task, all application tasks, regardless of
366priority, can be created and started before the initialization
367deletes itself.  This technique insures that all tasks begin to
368compete for execution time at the same instant -- when the user
369initialization task deletes itself.
370
371@subsection First Deadline Rule Example
372
373The First Deadline Rule can insure schedulability
374even when the Processor Utilization Rule fails.  The example
375below is a modification of the Processor Utilization Rule
376example where task execution time has been increased from 15 to
37725 units.  The following table details the RMS priority, period,
378execution time, and processor utilization for each task:
379
380@ifset use-ascii
381@example
382@group
383    +------------+----------+--------+-----------+-------------+
384    |    Task    |   RMS    | Period | Execution |  Processor  |
385    |            | Priority |        |   Time    | Utilization |
386    +------------+----------+--------+-----------+-------------+
387    |     1      |   High   |  100   |    25     |    0.25     |
388    +------------+----------+--------+-----------+-------------+
389    |     2      |  Medium  |  200   |    50     |    0.25     |
390    +------------+----------+--------+-----------+-------------+
391    |     3      |   Low    |  300   |   100     |    0.33     |
392    +------------+----------+--------+-----------+-------------+
393@end group
394@end example
395@end ifset
396
397@ifset use-tex
398@sp 1
399@tex
400\centerline{\vbox{\offinterlineskip\halign{
401\vrule\strut#&
402\hbox to 0.75in{\enskip\hfil#\hfil}&
403\vrule#&
404\hbox to 0.75in{\enskip\hfil#\hfil}&
405\vrule#&
406\hbox to 0.75in{\enskip\hfil#\hfil}&
407\vrule#&
408\hbox to 1.00in{\enskip\hfil#\hfil}&
409\vrule#&
410\hbox to 1.00in{\enskip\hfil#\hfil}&
411\vrule#\cr\noalign{\hrule}
412&\bf Task&& \bf RMS && \bf Period && \bf Execution &&\bf Processor&\cr
413& && \bf Priority && &&\bf Time &&\bf Utilization &\cr\noalign{\hrule}
414& 1 && High && 100 && 25 && 0.25 &\cr\noalign{\hrule}
415& 2 && Medium && 200 && 50 && 0.25 &\cr\noalign{\hrule}
416& 3 && Low && 300 && 100 && 0.33 &\cr\noalign{\hrule}
417}}\hfil}
418@end tex
419@end ifset
420 
421@ifset use-html
422@html
423<CENTER>
424  <TABLE COLS=5 WIDTH="80%" BORDER=2>
425<TR><TD ALIGN=center><STRONG>Task</STRONG></TD>
426    <TD ALIGN=center><STRONG>RMS Priority</STRONG></TD>
427    <TD ALIGN=center><STRONG>Period</STRONG></TD>
428    <TD ALIGN=center><STRONG>Execution Time</STRONG></TD>
429    <TD ALIGN=center><STRONG>Processor Utilization</STRONG></TD></TR>
430<TR><TD ALIGN=center>1</TD>
431    <TD ALIGN=center>High</TD>
432    <TD ALIGN=center>100</TD>
433    <TD ALIGN=center>25</TD>
434    <TD ALIGN=center>0.25</TD></TR>
435<TR><TD ALIGN=center>2</TD>
436    <TD ALIGN=center>Medium</TD>
437    <TD ALIGN=center>200</TD>
438    <TD ALIGN=center>50</TD>
439    <TD ALIGN=center>0.25</TD></TR>
440<TR><TD ALIGN=center>3</TD>
441    <TD ALIGN=center>Low</TD>
442    <TD ALIGN=center>300</TD>
443    <TD ALIGN=center>100</TD>
444    <TD ALIGN=center>0.33</TD></TR>
445  </TABLE>
446</CENTER>
447@end html
448@end ifset
449
450The total processor utilization for the modified task
451set is 0.83 which is above the upper bound of 3 * (2(1/3) - 1),
452or 0.779, imposed by the Processor Utilization Rule.  Therefore,
453this task set is not guaranteed to be schedulable using RMS.
454However, the First Deadline Rule can guarantee the
455schedulability of this task set.  This rule calls for one to
456examine each occurrence of deadline until either all tasks have
457met their deadline or one task failed to meet its first
458deadline.  The following table details the time of each deadline
459occurrence, the maximum number of times each task may have run,
460the total execution time, and whether all the deadlines have
461been met.
462
463@ifset use-ascii
464@example
465@group
466+----------+------+------+------+----------------------+---------------+
467| Deadline | Task | Task | Task |        Total         | All Deadlines |
468|   Time   |  1   |  2   |  3   |    Execution Time    |     Met?      |
469+----------+------+------+------+----------------------+---------------+
470|   100    |  1   |  1   |  1   |  25 + 50 + 100 = 175 |      NO       |
471+----------+------+------+------+----------------------+---------------+
472|   200    |  2   |  1   |  1   |  50 + 50 + 100 = 200 |     YES       |
473+----------+------+------+------+----------------------+---------------+
474@end group
475@end example
476@end ifset
477
478@ifset use-tex
479@sp 1
480@tex
481\centerline{\vbox{\offinterlineskip\halign{
482\vrule\strut#&
483\hbox to 0.75in{\enskip\hfil#\hfil}&
484\vrule#&
485\hbox to 0.75in{\enskip\hfil#\hfil}&
486\vrule#&
487\hbox to 0.75in{\enskip\hfil#\hfil}&
488\vrule#&
489\hbox to 0.75in{\enskip\hfil#\hfil}&
490\vrule#&
491\hbox to 2.00in{\enskip\hfil#\hfil}&
492\vrule#&
493\hbox to 1.00in{\enskip\hfil#\hfil}&
494\vrule#\cr\noalign{\hrule}
495&\bf Deadline&& \bf Task &&\bf Task&&\bf Task&&\bf Total          &&\bf All Deadlines &\cr
496&\bf Time    && \bf 1    &&\bf 2   &&\bf 3   &&\bf Execution Time &&\bf Net?&\cr\noalign{\hrule}
497& 100&& 1 && 1 && 1 && 25 + 50 + 100 = 175 && NO &\cr\noalign{\hrule}
498& 200&& 2 && 1 && 1 && 50 + 50 + 100 = 200 && YES &\cr\noalign{\hrule}
499}}\hfil}
500@end tex
501@end ifset
502 
503@ifset use-html
504@html
505<CENTER>
506  <TABLE COLS=6 WIDTH="80%" BORDER=2>
507<TR><TD ALIGN=center><STRONG>Deadline Time</STRONG></TD>
508    <TD ALIGN=center><STRONG>Task 1</STRONG></TD>
509    <TD ALIGN=center><STRONG>Task 2</STRONG></TD>
510    <TD ALIGN=center><STRONG>Task 3</STRONG></TD>
511    <TD ALIGN=center><STRONG>Total Execution Time</STRONG></TD>
512    <TD ALIGN=center><STRONG>All Deadlines Met?</STRONG></TD></TR>
513<TR><TD ALIGN=center>100</TD>
514    <TD ALIGN=center>1</TD>
515    <TD ALIGN=center>1</TD>
516    <TD ALIGN=center>1</TD>
517    <TD ALIGN=center>25 + 50 + 100 = 175</TD>
518    <TD ALIGN=center>NO</TD></TR>
519<TR><TD ALIGN=center>200</TD>
520    <TD ALIGN=center>2</TD>
521    <TD ALIGN=center>1</TD>
522    <TD ALIGN=center>1</TD>
523    <TD ALIGN=center>50 + 50 + 100 = 175</TD>
524    <TD ALIGN=center>YES</TD></TR>
525  </TABLE>
526</CENTER>
527@end html
528@end ifset
529
530The key to this analysis is to recognize when each
531task will execute.  For example at time 100, task 1 must have
532met its first deadline, but tasks 2 and 3 may also have begun
533execution.  In this example, at time 100 tasks 1 and 2 have
534completed execution and thus have met their first deadline.
535Tasks 1 and 2 have used (25 + 50) = 75 time units, leaving (100
536- 75) = 25 time units for task 3 to begin.  Because task 3 takes
537100 ticks to execute, it will not have completed execution at
538time 100.  Thus at time 100, all of the tasks except task 3 have
539met their first deadline.
540
541At time 200, task 1 must have met its second deadline
542and task 2 its first deadline.  As a result, of the first 200
543time units, task 1 uses (2 * 25) = 50 and task 2 uses 50,
544leaving (200 - 100) time units for task 3.  Task 3 requires 100
545time units to execute, thus it will have completed execution at
546time 200.  Thus, all of the tasks have met their first deadlines
547at time 200, and the task set is schedulable using the First
548Deadline Rule.
549
550@subsection Relaxation of Assumptions
551
552The assumptions used to develop the RMS
553schedulability rules are uncommon in most real-time systems.
554For example, it was assumed that tasks have constant unvarying
555execution time.  It is possible to relax this assumption, simply
556by using the worst-case execution time of each task.
557
558Another assumption is that the tasks are independent.
559This means that the tasks do not wait for one another or
560contend for resources.  This assumption can be relaxed by
561accounting for the amount of time a task spends waiting to
562acquire resources.  Similarly, each task's execution time must
563account for any I/O performed and any RTEMS directive calls.
564
565In addition, the assumptions did not account for the
566time spent executing interrupt service routines.  This can be
567accounted for by including all the processor utilization by
568interrupt service routines in the utilization calculation.
569Similarly, one should also account for the impact of delays in
570accessing local memory caused by direct memory access and other
571processors accessing local dual-ported memory.
572
573The assumption that nonperiodic tasks are used only
574for initialization or failure-recovery can be relaxed by placing
575all periodic tasks in the critical task set.  This task set can
576be scheduled and analyzed using RMS.  All nonperiodic tasks are
577placed in the non-critical task set.  Although the critical task
578set can be guaranteed to execute even under transient overload,
579the non-critical task set is not guaranteed to execute.
580
581In conclusion, the application designer must be fully
582cognizant of the system and its run-time behavior when
583performing schedulability analysis for a system using RMS.
584Every hardware and software factor which impacts the execution
585time of each task must be accounted for in the schedulability
586analysis.
587
588@subsection Further Reading
589
590For more information on Rate Monotonic Scheduling and
591its schedulability analysis, the reader is referred to the
592following:
593
594@itemize @code{ }
595@item @cite{C. L. Liu and J. W. Layland. "Scheduling Algorithms for
596Multiprogramming in a Hard Real Time Environment." @b{Journal of
597the Association of Computing Machinery}. January 1973. pp. 46-61.}
598
599@item @cite{John Lehoczky, Lui Sha, and Ye Ding. "The Rate Monotonic
600Scheduling Algorithm: Exact Characterization and Average Case
601Behavior."  @b{IEEE Real-Time Systems Symposium}. 1989. pp. 166-171.}
602
603@item @cite{Lui Sha and John Goodenough. "Real-Time Scheduling
604Theory and Ada."  @b{IEEE Computer}. April 1990. pp. 53-62.}
605
606@item @cite{Alan Burns. "Scheduling hard real-time systems: a
607review."  @b{Software Engineering Journal}. May 1991. pp. 116-128.}
608@end itemize
609
610@raisesections
611
612@section Operations
613
614@subsection Creating a Rate Monotonic Period
615
616The @code{@value{DIRPREFIX}rate_monotonic_create} directive creates a rate
617monotonic period which is to be used by the calling task to
618delineate a period.  RTEMS allocates a Period Control Block
619(PCB) from the PCB free list.  This data structure is used by
620RTEMS to manage the newly created rate monotonic period.  RTEMS
621returns a unique period ID to the application which is used by
622other rate monotonic manager directives to access this rate
623monotonic period.
624
625@subsection Manipulating a Period
626
627The @code{@value{DIRPREFIX}rate_monotonic_period} directive is used to
628establish and maintain periodic execution utilizing a previously
629created rate monotonic period.   Once initiated by the
630@code{@value{DIRPREFIX}rate_monotonic_period} directive, the period is
631said to run until it either expires or is reinitiated.  The state of the rate
632monotonic period results in one of the following scenarios:
633
634@itemize @bullet
635@item If the rate monotonic period is running, the calling
636task will be blocked for the remainder of the outstanding period
637and, upon completion of that period, the period will be
638reinitiated with the specified period.
639
640@item If the rate monotonic period is not currently running
641and has not expired, it is initiated with a length of period
642ticks and the calling task returns immediately.
643
644@item If the rate monotonic period has expired before the task
645invokes the @code{@value{DIRPREFIX}rate_monotonic_period} directive,
646the period will be initiated with a length of period ticks and the calling task
647returns immediately with a timeout error status.
648
649@end itemize
650
651@subsection Obtaining a Period's Status
652
653If the @code{@value{DIRPREFIX}rate_monotonic_period} directive is invoked
654with a period of @code{@value{RPREFIX}PERIOD_STATUS} ticks, the current
655state of the specified rate monotonic period will be returned.  The following
656table details the relationship between the period's status and
657the directive status code returned by the
658@code{@value{DIRPREFIX}rate_monotonic_period}
659directive:
660
661@itemize @bullet
662@item @code{@value{RPREFIX}SUCCESSFUL} - period is running
663
664@item @code{@value{RPREFIX}TIMEOUT} - period has expired
665
666@item @code{@value{RPREFIX}NOT_DEFINED} - period has never been initiated
667@end itemize
668
669Obtaining the status of a rate monotonic period does
670not alter the state or length of that period.
671
672@subsection Canceling a Period
673
674The @code{@value{DIRPREFIX}rate_monotonic_cancel} directive is used to stop
675the period maintained by the specified rate monotonic period.
676The period is stopped and the rate monotonic period can be
677reinitiated using the @code{@value{DIRPREFIX}rate_monotonic_period} directive.
678
679@subsection Deleting a Rate Monotonic Period
680
681The @code{@value{DIRPREFIX}rate_monotonic_delete} directive is used to delete
682a rate monotonic period.  If the period is running and has not
683expired, the period is automatically canceled.  The rate
684monotonic period's control block is returned to the PCB free
685list when it is deleted.  A rate monotonic period can be deleted
686by a task other than the task which created the period.
687
688@subsection Examples
689
690The following sections illustrate common uses of rate
691monotonic periods to construct periodic tasks.
692
693@subsection Simple Periodic Task
694
695This example consists of a single periodic task
696which, after initialization, executes every 100 clock ticks.
697
698@page
699@example
700rtems_task Periodic_task()
701@{
702  rtems_name        name;
703  rtems_id          period;
704  rtems_status_code status;
705
706  name = rtems_build_name( 'P', 'E', 'R', 'D' );
707
708  (void) rate_monotonic_create( name, &period );
709
710  while ( 1 ) @{
711    if ( rate_monotonic_period( period, 100 ) == TIMEOUT )
712      break;
713
714    /* Perform some periodic actions */
715  @}
716
717  /* missed period so delete period and SELF */
718
719  (void) rate_monotonic_delete( period );
720  (void) task_delete( SELF );
721@}
722@end example
723
724
725The above task creates a rate monotonic period as
726part of its initialization.  The first time the loop is
727executed, the @code{@value{DIRPREFIX}rate_monotonic_period}
728directive will initiate the period for 100 ticks and return
729immediately.  Subsequent invocations of the
730@code{@value{DIRPREFIX}rate_monotonic_period} directive will result
731in the task blocking for the remainder of the 100 tick period.
732If, for any reason, the body of the loop takes more than 100
733ticks to execute, the @code{@value{DIRPREFIX}rate_monotonic_period}
734directive will return the @code{@value{RPREFIX}TIMEOUT} status. 
735If the above task misses its deadline, it will delete the rate
736monotonic period and itself.
737
738@subsection Task with Multiple Periods
739
740This example consists of a single periodic task
741which, after initialization, performs two sets of actions every
742100 clock ticks.  The first set of actions is performed in the
743first forty clock ticks of every 100 clock ticks, while the
744second set of actions is performed between the fortieth and
745seventieth clock ticks.  The last thirty clock ticks are not
746used by this task.
747
748@page
749@example
750task Periodic_task()
751@{
752  rtems_name        name_1, name_2;
753  rtems_id          period_1, period_2;
754  rtems_status_code status;
755
756  name_1 = rtems_build_name( 'P', 'E', 'R', '1' );
757  name_2 = rtems_build_name( 'P', 'E', 'R', '2' );
758
759  (void ) rate_monotonic_create( name_1, &period_1 );
760  (void ) rate_monotonic_create( name_2, &period_2 );
761
762  while ( 1 ) @{
763    if ( rate_monotonic_period( period_1, 100 ) == TIMEOUT )
764      break;
765
766    if ( rate_monotonic_period( period_2, 40 ) == TIMEOUT )
767      break;
768
769    /*
770     *  Perform first set of actions between clock
771     *  ticks 0 and 39 of every 100 ticks.
772     */
773
774    if ( rate_monotonic_period( period_2, 30 ) == TIMEOUT )
775      break;
776
777    /*
778     *  Perform second set of actions between clock 40 and 69
779     *  of every 100 ticks.  THEN ...
780     *
781     *  Check to make sure we didn't miss the period_2 period.
782     */
783
784    if ( rate_monotonic_period( period_2, STATUS ) == TIMEOUT )
785      break;
786
787    (void) rate_monotonic_cancel( period_2 );
788  @}
789
790  /* missed period so delete period and SELF */
791
792  (void ) rate_monotonic_delete( period_1 );
793  (void ) rate_monotonic_delete( period_2 );
794  (void ) task_delete( SELF );
795@}
796@end example
797
798The above task creates two rate monotonic periods as
799part of its initialization.  The first time the loop is
800executed, the @code{@value{DIRPREFIX}rate_monotonic_period}
801directive will initiate the period_1 period for 100 ticks
802and return immediately.  Subsequent invocations of the
803@code{@value{DIRPREFIX}rate_monotonic_period} directive
804for period_1 will result in the task blocking for the remainder
805of the 100 tick period.  The period_2 period is used to control
806the execution time of the two sets of actions within each 100
807tick period established by period_1.  The
808@code{@value{DIRPREFIX}rate_monotonic_cancel( period_2 )}
809call is performed to insure that the period_2 period
810does not expire while the task is blocked on the period_1
811period.  If this cancel operation were not performed, every time
812the @code{@value{DIRPREFIX}rate_monotonic_period( period_1, 40 )}
813call is executed, except for the initial one, a directive status
814of @code{@value{RPREFIX}TIMEOUT} is returned.  It is important to
815note that every time this call is made, the period_1 period will be
816initiated immediately and the task will not block.
817
818If, for any reason, the task misses any deadline, the
819@code{@value{DIRPREFIX}rate_monotonic_period} directive will
820return the @code{@value{RPREFIX}TIMEOUT}
821directive status.  If the above task misses its deadline, it
822will delete the rate monotonic periods and itself.
823
824@section Directives
825
826This section details the rate monotonic manager's
827directives.  A subsection is dedicated to each of this manager's
828directives and describes the calling sequence, related
829constants, usage, and status codes.
830
831@page
832@subsection RATE_MONOTONIC_CREATE - Create a rate monotonic period
833
834@subheading CALLING SEQUENCE:
835
836@ifset is-C
837@c @findex rtems_rate_monotonic_create
838@example
839rtems_status_code rtems_rate_monotonic_create(
840  rtems_name  name,
841  rtems_id   *id
842);
843@end example
844@end ifset
845
846@ifset is-Ada
847@example
848procedure Rate_Monotonic_Create (
849   Name   : in     RTEMS.Name;
850   ID     :    out RTEMS.ID;
851   Result :    out RTEMS.Status_Codes
852);
853@end example
854@end ifset
855
856@subheading DIRECTIVE STATUS CODES:
857@code{@value{RPREFIX}SUCCESSFUL} - rate monotonic period created successfully@*
858@code{@value{RPREFIX}INVALID_NAME} - invalid task name@*
859@code{@value{RPREFIX}TOO_MANY} - too many periods created
860
861@subheading DESCRIPTION:
862
863This directive creates a rate monotonic period.  The
864assigned rate monotonic id is returned in id.  This id is used
865to access the period with other rate monotonic manager
866directives.  For control and maintenance of the rate monotonic
867period, RTEMS allocates a PCB from the local PCB free pool and
868initializes it.
869
870@subheading NOTES:
871
872This directive will not cause the calling task to be
873preempted.
874
875@page
876@subsection RATE_MONOTONIC_IDENT - Get ID of a period
877
878@subheading CALLING SEQUENCE:
879
880@ifset is-C
881@c @findex rtems_rate_monotonic_ident
882@example
883rtems_status_code rtems_rate_monotonic_ident(
884  rtems_name  name,
885  rtems_id   *id
886);
887@end example
888@end ifset
889
890@ifset is-Ada
891@example
892procedure Rate_Monotonic_Ident (
893   Name   : in     RTEMS.Name;
894   ID     :    out RTEMS.ID;
895   Result :    out RTEMS.Status_Codes
896);
897@end example
898@end ifset
899
900@subheading DIRECTIVE STATUS CODES:
901@code{@value{RPREFIX}SUCCESSFUL} - period identified successfully@*
902@code{@value{RPREFIX}INVALID_NAME} - period name not found
903
904@subheading DESCRIPTION:
905
906This directive obtains the period id associated with
907the period name to be acquired.  If the period name is not
908unique, then the period id will match one of the periods with
909that name.  However, this period id is not guaranteed to
910correspond to the desired period.  The period id is used to
911access this period in other rate monotonic manager directives.
912
913@subheading NOTES:
914
915This directive will not cause the running task to be
916preempted.
917
918@page
919@subsection RATE_MONOTONIC_CANCEL - Cancel a period
920
921@subheading CALLING SEQUENCE:
922
923@ifset is-C
924@c @findex rtems_rate_monotonic_cancel
925@example
926rtems_status_code rtems_rate_monotonic_cancel(
927  rtems_id id
928);
929@end example
930@end ifset
931
932@ifset is-Ada
933@example
934procedure Rate_Monotonic_Cancel (
935   ID     : in     RTEMS.ID;
936   Result :    out RTEMS.Status_Codes
937);
938@end example
939@end ifset
940
941@subheading DIRECTIVE STATUS CODES:
942@code{@value{RPREFIX}SUCCESSFUL} - period canceled successfully@*
943@code{@value{RPREFIX}INVALID_ID} - invalid rate monotonic period id@*
944@code{@value{RPREFIX}NOT_OWNER_OF_RESOURCE} - rate monotonic period not created by calling task
945
946@subheading DESCRIPTION:
947
948This directive cancels the rate monotonic period id.
949This period will be reinitiated by the next invocation of
950@code{@value{DIRPREFIX}rate_monotonic_period} with id.
951
952@subheading NOTES:
953
954This directive will not cause the running task to be
955preempted.
956
957The rate monotonic period specified by id must have
958been created by the calling task.
959
960@page
961@subsection RATE_MONOTONIC_DELETE - Delete a rate monotonic period
962
963@subheading CALLING SEQUENCE:
964
965@ifset is-C
966@c @findex rtems_rate_monotonic_delete
967@example
968rtems_status_code rtems_rate_monotonic_delete(
969  rtems_id id
970);
971@end example
972@end ifset
973
974@ifset is-Ada
975@example
976procedure Rate_Monotonic_Delete (
977   ID     : in     RTEMS.ID;
978   Result :    out RTEMS.Status_Codes
979);
980@end example
981@end ifset
982
983@subheading DIRECTIVE STATUS CODES:
984@code{@value{RPREFIX}SUCCESSFUL} - period deleted successfully@*
985@code{@value{RPREFIX}INVALID_ID} - invalid rate monotonic period id
986
987@subheading DESCRIPTION:
988
989This directive deletes the rate monotonic period
990specified by id.  If the period is running, it is automatically
991canceled.  The PCB for the deleted period is reclaimed by RTEMS.
992
993@subheading NOTES:
994
995This directive will not cause the running task to be
996preempted.
997
998A rate monotonic period can be deleted by a task
999other than the task which created the period.
1000
1001@page
1002@subsection RATE_MONOTONIC_PERIOD - Conclude current/Start next period
1003
1004@subheading CALLING SEQUENCE:
1005
1006@ifset is-C
1007@c @findex rtems_rate_monotonic_period
1008@example
1009rtems_status_code rtems_rate_monotonic_period(
1010  rtems_id       id,
1011  rtems_interval length
1012);
1013@end example
1014@end ifset
1015
1016@ifset is-Ada
1017@example
1018procedure Rate_Monotonic_Period (
1019   ID      : in     RTEMS.ID;
1020   Length  : in     RTEMS.Interval;
1021   Result  :    out RTEMS.Status_Codes
1022);
1023@end example
1024@end ifset
1025
1026@subheading DIRECTIVE STATUS CODES:
1027@code{@value{RPREFIX}SUCCESSFUL} - period initiated successfully@*
1028@code{@value{RPREFIX}INVALID_ID} - invalid rate monotonic period id@*
1029@code{@value{RPREFIX}NOT_OWNER_OF_RESOURCE} - period not created by calling task@*
1030@code{@value{RPREFIX}NOT_DEFINED} - period has never been initiated (only
1031possible when period is set to PERIOD_STATUS)@*
1032@code{@value{RPREFIX}TIMEOUT} - period has expired
1033
1034@subheading DESCRIPTION:
1035
1036This directive initiates the rate monotonic period id
1037with a length of period ticks.  If id is running, then the
1038calling task will block for the remainder of the period before
1039reinitiating the period with the specified period.  If id was
1040not running (either expired or never initiated), the period is
1041immediately initiated and the directive returns immediately.
1042
1043If invoked with a period of @code{@value{RPREFIX}PERIOD_STATUS} ticks, the
1044current state of id will be returned.  The directive status
1045indicates the current state of the period.  This does not alter
1046the state or period of the period.
1047
1048@subheading NOTES:
1049
1050This directive will not cause the running task to be preempted.
1051
1052---------------------
1053@page
1054@subsection RATE_MONOTONIC_GET_STATUS - Obtain status information on period
1055
1056@subheading CALLING SEQUENCE:
1057
1058@ifset is-C
1059@c @findex rtems_rate_monotonic_get_status
1060@example
1061rtems_status_code rtems_rate_monotonic_get_status(
1062  rtems_id                            id,
1063  rtems_rate_monotonic_period_status *status
1064);
1065@end example
1066@end ifset
1067
1068@ifset is-Ada
1069@example
1070procedure Rate_Monotonic_Get_Status (
1071   ID      : in     RTEMS.ID;
1072   Status  :    out RTEMS.Rate_Monotonic_Period_Status;
1073   Result  :    out RTEMS.Status_Codes
1074);
1075@end example
1076@end ifset
1077
1078@subheading DIRECTIVE STATUS CODES:
1079@code{@value{RPREFIX}SUCCESSFUL} - period initiated successfully@*
1080@code{@value{RPREFIX}INVALID_ID} - invalid rate monotonic period id@*
1081@code{@value{RPREFIX}INVALID_ADDRESS} - invalid address of status@*
1082
1083@subheading DESCRIPTION:
1084
1085This directive returns status information associated with
1086the rate monotonic period id in the following data @value{STRUCTURE}:
1087
1088@ifset is-C
1089@example
1090typedef struct @{
1091  rtems_rate_monotonic_period_states  state;
1092  unsigned32                          ticks_since_last_period;
1093  unsigned32                          ticks_executed_since_last_period;
1094@}  rtems_rate_monotonic_period_status;
1095@end example
1096@end ifset
1097
1098@ifset is-Ada
1099@example
1100type Rate_Monotonic_Period_Status is
1101   begin
1102      State                            : RTEMS.Rate_Monotonic_Period_States;
1103      Ticks_Since_Last_Period          : RTEMS.Unsigned32;
1104      Ticks_Executed_Since_Last_Period : RTEMS.Unsigned32;
1105   end record;
1106@end example
1107@end ifset
1108
1109@c RATE_MONOTONIC_INACTIVE does not have RTEMS_ in front of it.
1110
1111If the period's state is @code{RATE_MONOTONIC_INACTIVE}, both
1112ticks_since_last_period and ticks_executed_since_last_period
1113will be set to 0.  Otherwise, ticks_since_last_period will
1114contain the number of clock ticks which have occurred since
1115the last invocation of the
1116@code{@value{DIRPREFIX}rate_monotonic_period} directive.
1117Also in this case, the ticks_executed_since_last_period will indicate
1118how much processor time the owning task has consumed since the invocation
1119of the @code{@value{DIRPREFIX}rate_monotonic_period} directive.
1120
1121@subheading NOTES:
1122
1123This directive will not cause the running task to be preempted.
Note: See TracBrowser for help on using the repository browser.