From fd6dc8c8de4dbc7ecf8a82a597cd5b43476fc8e3 Mon Sep 17 00:00:00 2001 From: Amar Takhar Date: Sun, 17 Jan 2016 19:19:43 -0500 Subject: Split document into seperate files by section. --- c_user/rate_monotonic_manager.rst | 1069 +++++++++++++++++++++++++++++++++++++ 1 file changed, 1069 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..c22cd00 --- /dev/null +++ b/c_user/rate_monotonic_manager.rst @@ -0,0 +1,1069 @@ +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: + +- *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:: 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:: 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: + + ++------------+----------+--------+-----------+-------------+ +| Tas k | 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: +.. code:: c + ++------------+----------+--------+-----------+-------------+ +| 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. +.. code:: c + ++----------+------+------+------+----------------------+---------------+ +| 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: + +- ``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:: c + + 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:: c + + 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. + +RATE_MONOTONIC_CREATE - Create a rate monotonic period +------------------------------------------------------ +.. index:: create a period + +**CALLING SEQUENCE:** + +.. index:: rtems_rate_monotonic_create + +.. code:: c + + rtems_status_code rtems_rate_monotonic_create( + rtems_name name, + rtems_id \*id + ); + +**DIRECTIVE STATUS CODES:** + +``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. + +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:: c + + rtems_status_code rtems_rate_monotonic_ident( + rtems_name name, + rtems_id \*id + ); + +**DIRECTIVE STATUS CODES:** + +``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. + +RATE_MONOTONIC_CANCEL - Cancel a period +--------------------------------------- +.. index:: cancel a period + +**CALLING SEQUENCE:** + +.. index:: rtems_rate_monotonic_cancel + +.. code:: c + + rtems_status_code rtems_rate_monotonic_cancel( + rtems_id id + ); + +**DIRECTIVE STATUS CODES:** + +``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. + +RATE_MONOTONIC_DELETE - Delete a rate monotonic period +------------------------------------------------------ +.. index:: delete a period + +**CALLING SEQUENCE:** + +.. index:: rtems_rate_monotonic_delete + +.. code:: c + + rtems_status_code rtems_rate_monotonic_delete( + rtems_id id + ); + +**DIRECTIVE STATUS CODES:** + +``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. + +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:: c + + rtems_status_code rtems_rate_monotonic_period( + rtems_id id, + rtems_interval length + ); + +**DIRECTIVE STATUS CODES:** + +``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. + +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:: c + + rtems_status_code rtems_rate_monotonic_get_status( + rtems_id id, + rtems_rate_monotonic_period_status \*status + ); + +**DIRECTIVE STATUS CODES:** + +``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:: 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. + +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:: c + + rtems_status_code rtems_rate_monotonic_get_statistics( + rtems_id id, + rtems_rate_monotonic_period_statistics \*statistics + ); + +**DIRECTIVE STATUS CODES:** + +``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:: 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. + +RATE_MONOTONIC_RESET_STATISTICS - Reset statistics for a period +--------------------------------------------------------------- +.. index:: reset statistics of period + +**CALLING SEQUENCE:** + +.. index:: rtems_rate_monotonic_reset_statistics + +.. code:: c + + rtems_status_code rtems_rate_monotonic_reset_statistics( + rtems_id id + ); + +**DIRECTIVE STATUS CODES:** + +``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. + +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:: 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. + +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:: 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:: 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. + +.. COMMENT: COPYRIGHT (c) 1988-2007. + +.. COMMENT: On-Line Applications Research Corporation (OAR). + +.. COMMENT: All rights reserved. + -- cgit v1.2.3