From 72a62ad88f82fe1ffee50024db4dd0f3fa5806f7 Mon Sep 17 00:00:00 2001 From: Chris Johns Date: Thu, 3 Nov 2016 16:58:08 +1100 Subject: Rename all manuals with an _ to have a -. It helps released naming of files. --- c-user/rate_monotonic_manager.rst | 1088 +++++++++++++++++++++++++++++++++++++ 1 file changed, 1088 insertions(+) create mode 100644 c-user/rate_monotonic_manager.rst (limited to 'c-user/rate_monotonic_manager.rst') diff --git a/c-user/rate_monotonic_manager.rst b/c-user/rate_monotonic_manager.rst new file mode 100644 index 0000000..e0fc66b --- /dev/null +++ b/c-user/rate_monotonic_manager.rst @@ -0,0 +1,1088 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 1988-2008. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + +Rate Monotonic Manager +###################### + +.. index:: rate mononitonic tasks +.. index:: periodic tasks + +Introduction +============ + +The rate monotonic manager provides facilities to implement tasks which execute +in a periodic fashion. Critically, it also gathers information about the +execution of those periods and can provide important statistics to the user +which can be used to analyze and tune the application. The directives provided +by the rate monotonic manager are: + +- rtems_rate_monotonic_create_ - Create a rate monotonic period + +- rtems_rate_monotonic_ident_ - Get ID of a period + +- rtems_rate_monotonic_cancel_ - Cancel a period + +- rtems_rate_monotonic_delete_ - Delete a rate monotonic period + +- rtems_rate_monotonic_period_ - Conclude current/Start next period + +- rtems_rate_monotonic_get_status_ - Obtain status from a period + +- rtems_rate_monotonic_get_statistics_ - Obtain statistics from a period + +- rtems_rate_monotonic_reset_statistics_ - Reset statistics for a period + +- rtems_rate_monotonic_reset_all_statistics_ - Reset statistics for all periods + +- rtems_rate_monotonic_report_statistics_ - Print period statistics report + +Background +========== + +The rate monotonic manager provides facilities to manage the execution of +periodic tasks. This manager was designed to support application designers who +utilize the Rate Monotonic Scheduling Algorithm (RMS) to ensure that their +periodic tasks will meet their deadlines, even under transient overload +conditions. Although designed for hard real-time systems, the services +provided by the rate monotonic manager may be used by any application which +requires periodic tasks. + +Rate Monotonic Manager Required Support +--------------------------------------- + +A clock tick is required to support the functionality provided by this manager. + +Period Statistics +----------------- + +This manager maintains a set of statistics on each period object. These +statistics are reset implictly at period creation time and may be reset or +obtained at any time by the application. The following is a list of the +information kept: + +``owner`` + is the id of the thread that owns this period. + +``count`` + is the total number of periods executed. + +``missed_count`` + is the number of periods that were missed. + +``min_cpu_time`` + is the minimum amount of CPU execution time consumed on any execution of the + periodic loop. + +``max_cpu_time`` + is the maximum amount of CPU execution time consumed on any execution of the + periodic loop. + +``total_cpu_time`` + is the total amount of CPU execution time consumed by executions of the + periodic loop. + +``min_wall_time`` + is the minimum amount of wall time that passed on any execution of the + periodic loop. + +``max_wall_time`` + is the maximum amount of wall time that passed on any execution of the + periodic loop. + +``total_wall_time`` + is the total amount of wall time that passed during executions of the + periodic loop. + +Each period is divided into two consecutive phases. The period starts with the +active phase of the task and is followed by the inactive phase of the task. In +the inactive phase the task is blocked and waits for the start of the next +period. The inactive phase is skipped in case of a period miss. The wall time +includes the time during the active phase of the task on which the task is not +executing on a processor. The task is either blocked (for example it waits for +a resource) or a higher priority tasks executes, thus preventing it from +executing. In case the wall time exceeds the period time, then this is a +period miss. The gap between the wall time and the period time is the margin +between a period miss or success. + +The period statistics information is inexpensive to maintain and can provide +very useful insights into the execution characteristics of a periodic task +loop. But it is just information. The period statistics reported must be +analyzed by the user in terms of what the applications is. For example, in an +application where priorities are assigned by the Rate Monotonic Algorithm, it +would be very undesirable for high priority (i.e. frequency) tasks to miss +their period. Similarly, in nearly any application, if a task were supposed to +execute its periodic loop every 10 milliseconds and it averaged 11 +milliseconds, then application requirements are not being met. + +The information reported can be used to determine the "hot spots" in the +application. Given a period's id, the user can determine the length of that +period. From that information and the CPU usage, the user can calculate the +percentage of CPU time consumed by that periodic task. For example, a task +executing for 20 milliseconds every 200 milliseconds is consuming 10 percent of +the processor's execution time. This is usually enough to make it a good +candidate for optimization. + +However, execution time alone is not enough to gauge the value of optimizing a +particular task. It is more important to optimize a task executing 2 +millisecond every 10 milliseconds (20 percent of the CPU) than one executing 10 +milliseconds every 100 (10 percent of the CPU). As a general rule of thumb, +the higher frequency at which a task executes, the more important it is to +optimize that task. + +Rate Monotonic Manager Definitions +---------------------------------- +.. index:: periodic task, definition + +A periodic task is one which must be executed at a regular interval. The +interval between successive iterations of the task is referred to as its +period. Periodic tasks can be characterized by the length of their period and +execution time. The period and execution time of a task can be used to +determine the processor utilization for that task. Processor utilization is +the percentage of processor time used and can be calculated on a per-task or +system-wide basis. Typically, the task's worst-case execution time will be +less than its period. For example, a periodic task's requirements may state +that it should execute for 10 milliseconds every 100 milliseconds. Although +the execution time may be the average, worst, or best case, the worst-case +execution time is more appropriate for use when analyzing system behavior under +transient overload conditions... index:: aperiodic task, definition + +In contrast, an aperiodic task executes at irregular intervals and has only a +soft deadline. In other words, the deadlines for aperiodic tasks are not +rigid, but adequate response times are desirable. For example, an aperiodic +task may process user input from a terminal. + +.. index:: sporadic task, definition + +Finally, a sporadic task is an aperiodic task with a hard deadline and minimum +interarrival time. The minimum interarrival time is the minimum period of time +which exists between successive iterations of the task. For example, a +sporadic task could be used to process the pressing of a fire button on a +joystick. The mechanical action of the fire button ensures a minimum time +period between successive activations, but the missile must be launched by a +hard deadline. + +Rate Monotonic Scheduling Algorithm +----------------------------------- +.. index:: Rate Monotonic Scheduling Algorithm, definition +.. index:: RMS Algorithm, definition + +The Rate Monotonic Scheduling Algorithm (RMS) is important to real-time systems +designers because it allows one to guarantee that a set of tasks is +schedulable. A set of tasks is said to be schedulable if all of the tasks can +meet their deadlines. RMS provides a set of rules which can be used to perform +a guaranteed schedulability analysis for a task set. This analysis determines +whether a task set is schedulable under worst-case conditions and emphasizes +the predictability of the system's behavior. It has been proven that: + +.. sidebar:: *RMS* + + RMS is an optimal static priority algorithm for scheduling independent, + preemptible, periodic tasks on a single processor. + +RMS is optimal in the sense that if a set of tasks can be scheduled by any +static priority algorithm, then RMS will be able to schedule that task set. +RMS bases it schedulability analysis on the processor utilization level below +which all deadlines can be met. + +RMS calls for the static assignment of task priorities based upon their period. +The shorter a task's period, the higher its priority. For example, a task with +a 1 millisecond period has higher priority than a task with a 100 millisecond +period. If two tasks have the same period, then RMS does not distinguish +between the tasks. However, RTEMS specifies that when given tasks of equal +priority, the task which has been ready longest will execute first. RMS's +priority assignment scheme does not provide one with exact numeric values for +task priorities. For example, consider the following task set and priority +assignments: + ++--------------------+---------------------+---------------------+ +| Task | Period | Priority | +| | (in milliseconds) | | ++====================+=====================+=====================+ +| 1 | 100 | Low | ++--------------------+---------------------+---------------------+ +| 2 | 50 | Medium | ++--------------------+---------------------+---------------------+ +| 3 | 50 | Medium | ++--------------------+---------------------+---------------------+ +| 4 | 25 | High | ++--------------------+---------------------+---------------------+ + +RMS only calls for task 1 to have the lowest priority, task 4 to have the +highest priority, and tasks 2 and 3 to have an equal priority between that of +tasks 1 and 4. The actual RTEMS priorities assigned to the tasks must only +adhere to those guidelines. + +Many applications have tasks with both hard and soft deadlines. The tasks with +hard deadlines are typically referred to as the critical task set, with the +soft deadline tasks being the non-critical task set. The critical task set can +be scheduled using RMS, with the non-critical tasks not executing under +transient overload, by simply assigning priorities such that the lowest +priority critical task (i.e. longest period) has a higher priority than the +highest priority non-critical task. Although RMS may be used to assign +priorities to the non-critical tasks, it is not necessary. In this instance, +schedulability is only guaranteed for the critical task set. + +Schedulability Analysis +----------------------- + +.. index:: RMS schedulability analysis + +RMS allows application designers to ensure that tasks can meet all deadlines, +even under transient overload, without knowing exactly when any given task will +execute by applying proven schedulability analysis rules. + +Assumptions +~~~~~~~~~~~ + +The schedulability analysis rules for RMS were developed based on the following +assumptions: + +- The requests for all tasks for which hard deadlines exist are periodic, with + a constant interval between requests. + +- Each task must complete before the next request for it occurs. + +- The tasks are independent in that a task does not depend on the initiation or + completion of requests for other tasks. + +- The execution time for each task without preemption or interruption is + constant and does not vary. + +- Any non-periodic tasks in the system are special. These tasks displace + periodic tasks while executing and do not have hard, critical deadlines. + +Once the basic schedulability analysis is understood, some of the above +assumptions can be relaxed and the side-effects accounted for. + +Processor Utilization Rule +~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. index:: RMS Processor Utilization Rule + +The Processor Utilization Rule requires that processor utilization be +calculated based upon the period and execution time of each task. The fraction +of processor time spent executing task index is ``Time(index) / +Period(index)``. The processor utilization can be calculated as follows: + +.. code-block:: c + + Utilization = 0 + for index = 1 to maximum_tasks + Utilization = Utilization + (Time(index)/Period(index)) + +To ensure schedulability even under transient overload, the processor +utilization must adhere to the following rule: + +.. code-block:: c + + Utilization = maximum_tasks * (2**(1/maximum_tasks) - 1) + +As the number of tasks increases, the above formula approaches ln(2) for a +worst-case utilization factor of approximately 0.693. Many tasks sets can be +scheduled with a greater utilization factor. In fact, the average processor +utilization threshold for a randomly generated task set is approximately 0.88. + +Processor Utilization Rule Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This example illustrates the application of the Processor Utilization Rule to +an application with three critical periodic tasks. The following table details +the RMS priority, period, execution time, and processor utilization for each +task: + ++------------+----------+--------+-----------+-------------+ +| Task | RMS | Period | Execution | Processor | +| | Priority | | Time | Utilization | ++============+==========+========+===========+=============+ +| 1 | High | 100 | 15 | 0.15 | ++------------+----------+--------+-----------+-------------+ +| 2 | Medium | 200 | 50 | 0.25 | ++------------+----------+--------+-----------+-------------+ +| 3 | Low | 300 | 100 | 0.33 | ++------------+----------+--------+-----------+-------------+ + +The total processor utilization for this task set is 0.73 which is below the +upper bound of 3 * (2**(1/3) - 1), or 0.779, imposed by the Processor +Utilization Rule. Therefore, this task set is guaranteed to be schedulable +using RMS. + +First Deadline Rule +~~~~~~~~~~~~~~~~~~~ +.. index:: RMS First Deadline Rule + +If a given set of tasks do exceed the processor utilization upper limit imposed +by the Processor Utilization Rule, they can still be guaranteed to meet all +their deadlines by application of the First Deadline Rule. This rule can be +stated as follows: + +For a given set of independent periodic tasks, if each task meets its first +deadline when all tasks are started at the same time, then the deadlines will +always be met for any combination of start times. + +A key point with this rule is that ALL periodic tasks are assumed to start at +the exact same instant in time. Although this assumption may seem to be +invalid, RTEMS makes it quite easy to ensure. By having a non-preemptible user +initialization task, all application tasks, regardless of priority, can be +created and started before the initialization deletes itself. This technique +ensures that all tasks begin to compete for execution time at the same instant +- when the user initialization task deletes itself. + +First Deadline Rule Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The First Deadline Rule can ensure schedulability even when the Processor +Utilization Rule fails. The example below is a modification of the Processor +Utilization Rule example where task execution time has been increased from 15 +to 25 units. The following table details the RMS priority, period, execution +time, and processor utilization for each task: + ++------------+----------+--------+-----------+-------------+ +| Task | RMS | Period | Execution | Processor | +| | Priority | | Time | Utilization | ++============+==========+========+===========+=============+ +| 1 | High | 100 | 25 | 0.25 | ++------------+----------+--------+-----------+-------------+ +| 2 | Medium | 200 | 50 | 0.25 | ++------------+----------+--------+-----------+-------------+ +| 3 | Low | 300 | 100 | 0.33 | ++------------+----------+--------+-----------+-------------+ + +The total processor utilization for the modified task set is 0.83 which is +above the upper bound of 3 * (2**(1/3) - 1), or 0.779, imposed by the Processor +Utilization Rule. Therefore, this task set is not guaranteed to be schedulable +using RMS. However, the First Deadline Rule can guarantee the schedulability +of this task set. This rule calls for one to examine each occurrence of +deadline until either all tasks have met their deadline or one task failed to +meet its first deadline. The following table details the time of each deadline +occurrence, the maximum number of times each task may have run, the total +execution time, and whether all the deadlines have been met: + ++----------+------+------+------+----------------------+---------------+ +| Deadline | Task | Task | Task | Total | All Deadlines | +| Time | 1 | 2 | 3 | Execution Time | Met? | ++==========+======+======+======+======================+===============+ +| 100 | 1 | 1 | 1 | 25 + 50 + 100 = 175 | NO | ++----------+------+------+------+----------------------+---------------+ +| 200 | 2 | 1 | 1 | 50 + 50 + 100 = 200 | YES | ++----------+------+------+------+----------------------+---------------+ + +The key to this analysis is to recognize when each task will execute. For +example at time 100, task 1 must have met its first deadline, but tasks 2 and 3 +may also have begun execution. In this example, at time 100 tasks 1 and 2 have +completed execution and thus have met their first deadline. Tasks 1 and 2 have +used (25 + 50) = 75 time units, leaving (100 - 75) = 25 time units for task 3 +to begin. Because task 3 takes 100 ticks to execute, it will not have +completed execution at time 100. Thus at time 100, all of the tasks except +task 3 have met their first deadline. + +At time 200, task 1 must have met its second deadline and task 2 its first +deadline. As a result, of the first 200 time units, task 1 uses (2 * 25) = 50 +and task 2 uses 50, leaving (200 - 100) time units for task 3. Task 3 requires +100 time units to execute, thus it will have completed execution at time 200. +Thus, all of the tasks have met their first deadlines at time 200, and the task +set is schedulable using the First Deadline Rule. + +Relaxation of Assumptions +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The assumptions used to develop the RMS schedulability rules are uncommon in +most real-time systems. For example, it was assumed that tasks have constant +unvarying execution time. It is possible to relax this assumption, simply by +using the worst-case execution time of each task. + +Another assumption is that the tasks are independent. This means that the +tasks do not wait for one another or contend for resources. This assumption +can be relaxed by accounting for the amount of time a task spends waiting to +acquire resources. Similarly, each task's execution time must account for any +I/O performed and any RTEMS directive calls. + +In addition, the assumptions did not account for the time spent executing +interrupt service routines. This can be accounted for by including all the +processor utilization by interrupt service routines in the utilization +calculation. Similarly, one should also account for the impact of delays in +accessing local memory caused by direct memory access and other processors +accessing local dual-ported memory. + +The assumption that nonperiodic tasks are used only for initialization or +failure-recovery can be relaxed by placing all periodic tasks in the critical +task set. This task set can be scheduled and analyzed using RMS. All +nonperiodic tasks are placed in the non-critical task set. Although the +critical task set can be guaranteed to execute even under transient overload, +the non-critical task set is not guaranteed to execute. + +In conclusion, the application designer must be fully cognizant of the system +and its run-time behavior when performing schedulability analysis for a system +using RMS. Every hardware and software factor which impacts the execution time +of each task must be accounted for in the schedulability analysis. + +Further Reading +~~~~~~~~~~~~~~~ + +For more information on Rate Monotonic Scheduling and its schedulability +analysis, the reader is referred to the following: + +- C. L. Liu and J. W. Layland. "Scheduling Algorithms for Multiprogramming in a + Hard Real Time Environment." *Journal of the Association of Computing + Machinery*. January 1973. pp. 46-61. + +- John Lehoczky, Lui Sha, and Ye Ding. "The Rate Monotonic Scheduling + Algorithm: Exact Characterization and Average Case Behavior." *IEEE + Real-Time Systems Symposium*. 1989. pp. 166-171. + +- Lui Sha and John Goodenough. "Real-Time Scheduling theory and Ada." *IEEE + Computer*. April 1990. pp. 53-62. + +- Alan Burns. "Scheduling hard real-time systems: a review." *Software + Engineering Journal*. May 1991. pp. 116-128. + +Operations +========== + +Creating a Rate Monotonic Period +-------------------------------- + +The ``rtems_rate_monotonic_create`` directive creates a rate monotonic period +which is to be used by the calling task to delineate a period. RTEMS allocates +a Period Control Block (PCB) from the PCB free list. This data structure is +used by RTEMS to manage the newly created rate monotonic period. RTEMS returns +a unique period ID to the application which is used by other rate monotonic +manager directives to access this rate monotonic period. + +Manipulating a Period +--------------------- + +The ``rtems_rate_monotonic_period`` directive is used to establish and maintain +periodic execution utilizing a previously created rate monotonic period. Once +initiated by the ``rtems_rate_monotonic_period`` directive, the period is said +to run until it either expires or is reinitiated. The state of the rate +monotonic period results in one of the following scenarios: + +- If the rate monotonic period is running, the calling task will be blocked for + the remainder of the outstanding period and, upon completion of that period, + the period will be reinitiated with the specified period. + +- If the rate monotonic period is not currently running and has not expired, it + is initiated with a length of period ticks and the calling task returns + immediately. + +- If the rate monotonic period has expired before the task invokes the + ``rtems_rate_monotonic_period`` directive, the period will be initiated with + a length of period ticks and the calling task returns immediately with a + timeout error status. + +Obtaining the Status of a Period +-------------------------------- + +If the ``rtems_rate_monotonic_period`` directive is invoked with a period of +``RTEMS_PERIOD_STATUS`` ticks, the current state of the specified rate +monotonic period will be returned. The following table details the +relationship between the period's status and the directive status code returned +by the ``rtems_rate_monotonic_period`` directive: + +.. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - period is running + * - ``RTEMS_TIMEOUT`` + - period has expired + * - ``RTEMS_NOT_DEFINED`` + - period has never been initiated + +Obtaining the status of a rate monotonic period does not alter the state or +length of that period. + +Canceling a Period +------------------ + +The ``rtems_rate_monotonic_cancel`` directive is used to stop the period +maintained by the specified rate monotonic period. The period is stopped and +the rate monotonic period can be reinitiated using the +``rtems_rate_monotonic_period`` directive. + +Deleting a Rate Monotonic Period +-------------------------------- + +The ``rtems_rate_monotonic_delete`` directive is used to delete a rate +monotonic period. If the period is running and has not expired, the period is +automatically canceled. The rate monotonic period's control block is returned +to the PCB free list when it is deleted. A rate monotonic period can be +deleted by a task other than the task which created the period. + +Examples +-------- + +The following sections illustrate common uses of rate monotonic periods to +construct periodic tasks. + +Simple Periodic Task +-------------------- + +This example consists of a single periodic task which, after initialization, +executes every 100 clock ticks. + +.. code-block:: c + :linenos: + + rtems_task Periodic_task(rtems_task_argument arg) + { + rtems_name name; + rtems_id period; + rtems_status_code status; + name = rtems_build_name( 'P', 'E', 'R', 'D' ); + status = rtems_rate_monotonic_create( name, &period ); + if ( status != RTEMS_STATUS_SUCCESSFUL ) { + printf( "rtems_monotonic_create failed with status of %d.\n", rc ); + exit( 1 ); + } + while ( 1 ) { + if ( rtems_rate_monotonic_period( period, 100 ) == RTEMS_TIMEOUT ) + break; + /* Perform some periodic actions */ + } + /* missed period so delete period and SELF */ + status = rtems_rate_monotonic_delete( period ); + if ( status != RTEMS_STATUS_SUCCESSFUL ) { + printf( "rtems_rate_monotonic_delete failed with status of %d.\n", status ); + exit( 1 ); + } + status = rtems_task_delete( SELF ); /* should not return */ + printf( "rtems_task_delete returned with status of %d.\n", status ); + exit( 1 ); + } + +The above task creates a rate monotonic period as part of its initialization. +The first time the loop is executed, the ``rtems_rate_monotonic_period`` +directive will initiate the period for 100 ticks and return immediately. +Subsequent invocations of the ``rtems_rate_monotonic_period`` directive will +result in the task blocking for the remainder of the 100 tick period. If, for +any reason, the body of the loop takes more than 100 ticks to execute, the +``rtems_rate_monotonic_period`` directive will return the ``RTEMS_TIMEOUT`` +status. If the above task misses its deadline, it will delete the rate +monotonic period and itself. + +Task with Multiple Periods +-------------------------- + +This example consists of a single periodic task which, after initialization, +performs two sets of actions every 100 clock ticks. The first set of actions +is performed in the first forty clock ticks of every 100 clock ticks, while the +second set of actions is performed between the fortieth and seventieth clock +ticks. The last thirty clock ticks are not used by this task. + +.. code-block:: c + :linenos: + + rtems_task Periodic_task(rtems_task_argument arg) + { + rtems_name name_1, name_2; + rtems_id period_1, period_2; + rtems_status_code status; + name_1 = rtems_build_name( 'P', 'E', 'R', '1' ); + name_2 = rtems_build_name( 'P', 'E', 'R', '2' ); + (void ) rtems_rate_monotonic_create( name_1, &period_1 ); + (void ) rtems_rate_monotonic_create( name_2, &period_2 ); + while ( 1 ) { + if ( rtems_rate_monotonic_period( period_1, 100 ) == TIMEOUT ) + break; + if ( rtems_rate_monotonic_period( period_2, 40 ) == TIMEOUT ) + break; + /* + * Perform first set of actions between clock + * ticks 0 and 39 of every 100 ticks. + */ + if ( rtems_rate_monotonic_period( period_2, 30 ) == TIMEOUT ) + break; + /* + * Perform second set of actions between clock 40 and 69 + * of every 100 ticks. THEN ... + * + * Check to make sure we didn't miss the period_2 period. + */ + if ( rtems_rate_monotonic_period( period_2, STATUS ) == TIMEOUT ) + break; + (void) rtems_rate_monotonic_cancel( period_2 ); + } + /* missed period so delete period and SELF */ + (void ) rtems_rate_monotonic_delete( period_1 ); + (void ) rtems_rate_monotonic_delete( period_2 ); + (void ) task_delete( SELF ); + } + +The above task creates two rate monotonic periods as part of its +initialization. The first time the loop is executed, the +``rtems_rate_monotonic_period`` directive will initiate the period_1 period for +100 ticks and return immediately. Subsequent invocations of the +``rtems_rate_monotonic_period`` directive for period_1 will result in the task +blocking for the remainder of the 100 tick period. The period_2 period is used +to control the execution time of the two sets of actions within each 100 tick +period established by period_1. The ``rtems_rate_monotonic_cancel( period_2 +)`` call is performed to ensure that the period_2 period does not expire while +the task is blocked on the period_1 period. If this cancel operation were not +performed, every time the ``rtems_rate_monotonic_period( period_2, 40 )`` call +is executed, except for the initial one, a directive status of +``RTEMS_TIMEOUT`` is returned. It is important to note that every time this +call is made, the period_2 period will be initiated immediately and the task +will not block. + +If, for any reason, the task misses any deadline, the +``rtems_rate_monotonic_period`` directive will return the ``RTEMS_TIMEOUT`` +directive status. If the above task misses its deadline, it will delete the +rate monotonic periods and itself. + +Directives +========== + +This section details the rate monotonic manager's directives. A subsection is +dedicated to each of this manager's directives and describes the calling +sequence, related constants, usage, and status codes. + +.. _rtems_rate_monotonic_create: + +RATE_MONOTONIC_CREATE - Create a rate monotonic period +------------------------------------------------------ +.. index:: create a period + +**CALLING SEQUENCE:** + +.. index:: rtems_rate_monotonic_create + +.. code-block:: c + + rtems_status_code rtems_rate_monotonic_create( + rtems_name name, + rtems_id *id + ); + +**DIRECTIVE STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - rate monotonic period created successfully + * - ``RTEMS_INVALID_NAME`` + - invalid period name + * - ``RTEMS_TOO_MANY`` + - too many periods created + +**DESCRIPTION:** + +This directive creates a rate monotonic period. The assigned rate monotonic id +is returned in id. This id is used to access the period with other rate +monotonic manager directives. For control and maintenance of the rate +monotonic period, RTEMS allocates a PCB from the local PCB free pool and +initializes it. + +**NOTES:** + +This directive will not cause the calling task to be preempted. + +.. _rtems_rate_monotonic_ident: + +RATE_MONOTONIC_IDENT - Get ID of a period +----------------------------------------- +.. index:: get ID of a period +.. index:: obtain ID of a period + +**CALLING SEQUENCE:** + +.. index:: rtems_rate_monotonic_ident + +.. code-block:: c + + rtems_status_code rtems_rate_monotonic_ident( + rtems_name name, + rtems_id *id + ); + +**DIRECTIVE STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - period identified successfully + * - ``RTEMS_INVALID_NAME`` + - period name not found + +**DESCRIPTION:** + +This directive obtains the period id associated with the period name to be +acquired. If the period name is not unique, then the period id will match one +of the periods with that name. However, this period id is not guaranteed to +correspond to the desired period. The period id is used to access this period +in other rate monotonic manager directives. + +**NOTES:** + +This directive will not cause the running task to be preempted. + +.. _rtems_rate_monotonic_cancel: + +RATE_MONOTONIC_CANCEL - Cancel a period +--------------------------------------- +.. index:: cancel a period + +**CALLING SEQUENCE:** + +.. index:: rtems_rate_monotonic_cancel + +.. code-block:: c + + rtems_status_code rtems_rate_monotonic_cancel( + rtems_id id + ); + +**DIRECTIVE STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - period canceled successfully + * - ``RTEMS_INVALID_ID`` + - invalid rate monotonic period id + * - ``RTEMS_NOT_OWNER_OF_RESOURCE`` + - rate monotonic period not created by calling task + +**DESCRIPTION:** + +This directive cancels the rate monotonic period id. This period will be +reinitiated by the next invocation of ``rtems_rate_monotonic_period`` with id. + +**NOTES:** + +This directive will not cause the running task to be preempted. + +The rate monotonic period specified by id must have been created by the calling +task. + +.. _rtems_rate_monotonic_delete: + +RATE_MONOTONIC_DELETE - Delete a rate monotonic period +------------------------------------------------------ +.. index:: delete a period + +**CALLING SEQUENCE:** + +.. index:: rtems_rate_monotonic_delete + +.. code-block:: c + + rtems_status_code rtems_rate_monotonic_delete( + rtems_id id + ); + +**DIRECTIVE STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - period deleted successfully + * - ``RTEMS_INVALID_ID`` + - invalid rate monotonic period id + +**DESCRIPTION:** + +This directive deletes the rate monotonic period specified by id. If the +period is running, it is automatically canceled. The PCB for the deleted +period is reclaimed by RTEMS. + +**NOTES:** + +This directive will not cause the running task to be preempted. + +A rate monotonic period can be deleted by a task other than the task which +created the period. + +.. _rtems_rate_monotonic_period: + +RATE_MONOTONIC_PERIOD - Conclude current/Start next period +---------------------------------------------------------- +.. index:: conclude current period +.. index:: start current period +.. index:: period initiation + +**CALLING SEQUENCE:** + +.. index:: rtems_rate_monotonic_period + +.. code-block:: c + + rtems_status_code rtems_rate_monotonic_period( + rtems_id id, + rtems_interval length + ); + +**DIRECTIVE STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - period initiated successfully + * - ``RTEMS_INVALID_ID`` + - invalid rate monotonic period id + * - ``RTEMS_NOT_OWNER_OF_RESOURCE`` + - period not created by calling task + * - ``RTEMS_NOT_DEFINED`` + - period has never been initiated (only possible when period is set to PERIOD_STATUS) + * - ``RTEMS_TIMEOUT`` + - period has expired + +**DESCRIPTION:** + +This directive initiates the rate monotonic period id with a length of period +ticks. If id is running, then the calling task will block for the remainder of +the period before reinitiating the period with the specified period. If id was +not running (either expired or never initiated), the period is immediately +initiated and the directive returns immediately. + +If invoked with a period of ``RTEMS_PERIOD_STATUS`` ticks, the current state of +id will be returned. The directive status indicates the current state of the +period. This does not alter the state or period of the period. + +**NOTES:** + +This directive will not cause the running task to be preempted. + +.. _rtems_rate_monotonic_get_status: + +RATE_MONOTONIC_GET_STATUS - Obtain status from a period +------------------------------------------------------- +.. index:: get status of period +.. index:: obtain status of period + +**CALLING SEQUENCE:** + +.. index:: rtems_rate_monotonic_get_status + +.. code-block:: c + + rtems_status_code rtems_rate_monotonic_get_status( + rtems_id id, + rtems_rate_monotonic_period_status *status + ); + +**DIRECTIVE STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - period initiated successfully + * - ``RTEMS_INVALID_ID`` + - invalid rate monotonic period id + * - ``RTEMS_INVALID_ADDRESS`` + - invalid address of status + +**DESCRIPTION:** + +This directive returns status information associated with the rate monotonic +period id in the following data structure: + +.. index:: rtems_rate_monotonic_period_status + +.. code-block:: c + + typedef struct { + rtems_id owner; + rtems_rate_monotonic_period_states state; + rtems_rate_monotonic_period_time_t since_last_period; + rtems_thread_cpu_usage_t executed_since_last_period; + } rtems_rate_monotonic_period_status; + +.. COMMENT: RATE_MONOTONIC_INACTIVE does not have RTEMS in front of it. + +A configure time option can be used to select whether the time information is +given in ticks or seconds and nanoseconds. The default is seconds and +nanoseconds. If the period's state is ``RATE_MONOTONIC_INACTIVE``, both time +values will be set to 0. Otherwise, both time values will contain time +information since the last invocation of the ``rtems_rate_monotonic_period`` +directive. More specifically, the ticks_since_last_period value contains the +elapsed time which has occurred since the last invocation of the +``rtems_rate_monotonic_period`` directive and the +``ticks_executed_since_last_period`` contains how much processor time the +owning task has consumed since the invocation of the +``rtems_rate_monotonic_period`` directive. + +**NOTES:** + +This directive will not cause the running task to be preempted. + +.. _rtems_rate_monotonic_get_statistics: + +RATE_MONOTONIC_GET_STATISTICS - Obtain statistics from a period +--------------------------------------------------------------- +.. index:: get statistics of period +.. index:: obtain statistics of period + +**CALLING SEQUENCE:** + +.. index:: rtems_rate_monotonic_get_statistics + +.. code-block:: c + + rtems_status_code rtems_rate_monotonic_get_statistics( + rtems_id id, + rtems_rate_monotonic_period_statistics *statistics + ); + +**DIRECTIVE STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - period initiated successfully + * - ``RTEMS_INVALID_ID`` + - invalid rate monotonic period id + * - ``RTEMS_INVALID_ADDRESS`` + - invalid address of statistics + +**DESCRIPTION:** + +This directive returns statistics information associated with the rate +monotonic period id in the following data structure: + +.. index:: rtems_rate_monotonic_period_statistics + +.. code-block:: c + + typedef struct { + uint32_t count; + uint32_t missed_count; + #ifdef RTEMS_ENABLE_NANOSECOND_CPU_USAGE_STATISTICS + struct timespec min_cpu_time; + struct timespec max_cpu_time; + struct timespec total_cpu_time; + #else + uint32_t min_cpu_time; + uint32_t max_cpu_time; + uint32_t total_cpu_time; + #endif + #ifdef RTEMS_ENABLE_NANOSECOND_RATE_MONOTONIC_STATISTICS + struct timespec min_wall_time; + struct timespec max_wall_time; + struct timespec total_wall_time; + #else + uint32_t min_wall_time; + uint32_t max_wall_time; + uint32_t total_wall_time; + #endif + } rtems_rate_monotonic_period_statistics; + +This directive returns the current statistics information for the period +instance assocaited with ``id``. The information returned is indicated by the +structure above. + +**NOTES:** + +This directive will not cause the running task to be preempted. + +.. _rtems_rate_monotonic_reset_statistics: + +RATE_MONOTONIC_RESET_STATISTICS - Reset statistics for a period +--------------------------------------------------------------- +.. index:: reset statistics of period + +**CALLING SEQUENCE:** + +.. index:: rtems_rate_monotonic_reset_statistics + +.. code-block:: c + + rtems_status_code rtems_rate_monotonic_reset_statistics( + rtems_id id + ); + +**DIRECTIVE STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - period initiated successfully + * - ``RTEMS_INVALID_ID`` + - invalid rate monotonic period id + +**DESCRIPTION:** + +This directive resets the statistics information associated with this rate +monotonic period instance. + +**NOTES:** + +This directive will not cause the running task to be preempted. + +.. _rtems_rate_monotonic_reset_all_statistics: + +RATE_MONOTONIC_RESET_ALL_STATISTICS - Reset statistics for all periods +---------------------------------------------------------------------- +.. index:: reset statistics of all periods + +**CALLING SEQUENCE:** + +.. index:: rtems_rate_monotonic_reset_all_statistics + +.. code-block:: c + + void rtems_rate_monotonic_reset_all_statistics(void); + +**DIRECTIVE STATUS CODES:** + +NONE + +**DESCRIPTION:** + +This directive resets the statistics information associated with all rate +monotonic period instances. + +**NOTES:** + +This directive will not cause the running task to be preempted. + +.. _rtems_rate_monotonic_report_statistics: + +RATE_MONOTONIC_REPORT_STATISTICS - Print period statistics report +----------------------------------------------------------------- +.. index:: print period statistics report +.. index:: period statistics report + +**CALLING SEQUENCE:** + +.. index:: rtems_rate_monotonic_report_statistics + +.. code-block:: c + + void rtems_rate_monotonic_report_statistics(void); + +**DIRECTIVE STATUS CODES:** + +NONE + +**DESCRIPTION:** + +This directive prints a report on all active periods which have executed at +least one period. The following is an example of the output generated by this +directive. + +.. index:: rtems_rate_monotonic_period_statistics + +.. code-block:: c + + ID OWNER PERIODS MISSED CPU TIME WALL TIME + MIN/MAX/AVG MIN/MAX/AVG + 0x42010001 TA1 502 0 0/1/0.99 0/0/0.00 + 0x42010002 TA2 502 0 0/1/0.99 0/0/0.00 + 0x42010003 TA3 501 0 0/1/0.99 0/0/0.00 + 0x42010004 TA4 501 0 0/1/0.99 0/0/0.00 + 0x42010005 TA5 10 0 0/1/0.90 0/0/0.00 + +**NOTES:** + +This directive will not cause the running task to be preempted. -- cgit v1.2.3