source: rtems-docs/ada_user/rate_monotonic_manager.rst @ 4783b0d

4.115
Last change on this file since 4783b0d was 4783b0d, checked in by Amar Takhar <amar@…>, on 01/17/16 at 16:37:28

Split document into seperate files by section.

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