diff options
| -rw-r--r-- | c-user/index.rst | 2 | ||||
| -rw-r--r-- | c-user/rate-monotonic/background.rst | 390 | ||||
| -rw-r--r-- | c-user/rate-monotonic/directives.rst | 474 | ||||
| -rw-r--r-- | c-user/rate-monotonic/index.rst | 16 | ||||
| -rw-r--r-- | c-user/rate-monotonic/introduction.rst | 33 | ||||
| -rw-r--r-- | c-user/rate-monotonic/operations.rst | 200 | ||||
| -rw-r--r-- | c-user/rate_monotonic_manager.rst | 1091 |
7 files changed, 1114 insertions, 1092 deletions
diff --git a/c-user/index.rst b/c-user/index.rst index 6de3f97..4cf9e32 100644 --- a/c-user/index.rst +++ b/c-user/index.rst @@ -34,7 +34,7 @@ RTEMS Classic API Guide (|version|). interrupt/index clock/index timer_manager - rate_monotonic_manager + rate-monotonic/index semaphore/index barrier/index message/index diff --git a/c-user/rate-monotonic/background.rst b/c-user/rate-monotonic/background.rst new file mode 100644 index 0000000..9ca7dff --- /dev/null +++ b/c-user/rate-monotonic/background.rst @@ -0,0 +1,390 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) +.. Copyright (C) 2017 Kuan-Hsun Chen. + +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. + +.. index:: periodic task, definition + +Periodicity Definitions +---------------------------------- + +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. + +.. index:: Rate Monotonic Scheduling Algorithm, definition +.. index:: RMS Algorithm, definition + +Rate Monotonic Scheduling Algorithm +----------------------------------- + +The Rate Monotonic Scheduling Algorithm (RMS) is important to real-time systems +designers because it allows one to sufficiently guarantee that a set of tasks +is schedulable (see :cite:`Liu:1973:Scheduling`, :cite:`Lehoczky:1989:RM`, +:cite:`Sha:1990:Ada`, :cite:`Burns:1991:Review`). + +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 fixed-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 +fixed-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. + +.. index:: RMS schedulability analysis + +Schedulability Analysis +----------------------- + +RMS allows application designers to ensure that tasks can meet all deadlines under fixed-priority assignment, +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. + +.. index:: RMS Processor Utilization Rule + +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(i) +/ Period(i)``. The processor utilization can be calculated as follows +where n is the number of tasks in the set being analyzed: + +.. math:: + + Utilization = \sum_{i=1}^{n} Time_i/Period_i + +To ensure schedulability even under transient overload, the processor +utilization must adhere to the following rule: + +.. math:: + + maximumUtilization = n * (2^{\frac{1}{n}} - 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. +See more detail in :cite:`Liu:1973:Scheduling`. + +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. + +.. index:: RMS First Deadline Rule + +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. +See more detail in :cite:`Lehoczky:1989:RM`. + +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. diff --git a/c-user/rate-monotonic/directives.rst b/c-user/rate-monotonic/directives.rst new file mode 100644 index 0000000..d100c81 --- /dev/null +++ b/c-user/rate-monotonic/directives.rst @@ -0,0 +1,474 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) +.. Copyright (C) 2017 Kuan-Hsun Chen. + +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. + +.. raw:: latex + + \clearpage + +.. index:: create a period +.. index:: rtems_rate_monotonic_create + +.. _rtems_rate_monotonic_create: + +RATE_MONOTONIC_CREATE - Create a rate monotonic period +------------------------------------------------------ + +CALLING SEQUENCE: + .. 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 may cause the calling task to be preempted due to an + obtain and release of the object allocator mutex. + +.. raw:: latex + + \clearpage + +.. index:: get ID of a period +.. index:: obtain ID of a period +.. index:: rtems_rate_monotonic_ident + +.. _rtems_rate_monotonic_ident: + +RATE_MONOTONIC_IDENT - Get ID of a period +----------------------------------------- + +CALLING SEQUENCE: + .. 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. + +.. raw:: latex + + \clearpage + +.. index:: cancel a period +.. index:: rtems_rate_monotonic_cancel + +.. _rtems_rate_monotonic_cancel: + +RATE_MONOTONIC_CANCEL - Cancel a period +--------------------------------------- + +CALLING SEQUENCE: + .. 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. + +.. raw:: latex + + \clearpage + +.. index:: rtems_rate_monotonic_delete +.. index:: delete a period + +.. _rtems_rate_monotonic_delete: + +RATE_MONOTONIC_DELETE - Delete a rate monotonic period +------------------------------------------------------ + +CALLING SEQUENCE: + .. 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 may cause the calling task to be preempted due to an + obtain and release of the object allocator mutex. + + A rate monotonic period can be deleted by a task other than the task which + created the period. + +.. raw:: latex + + \clearpage + +.. index:: conclude current period +.. index:: start current period +.. index:: period initiation +.. index:: rtems_rate_monotonic_period + +.. _rtems_rate_monotonic_period: + +RATE_MONOTONIC_PERIOD - Conclude current/Start next period +---------------------------------------------------------- + +CALLING SEQUENCE: + .. 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 id has expired its period, the postponed job will be released immediately + and the following calls of this directive will release postponed + jobs until there is no more deadline miss. + + 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. + +.. raw:: latex + + \clearpage + +.. index:: get status of period +.. index:: obtain status of period +.. index:: rtems_rate_monotonic_get_status + +.. _rtems_rate_monotonic_get_status: + +RATE_MONOTONIC_GET_STATUS - Obtain status from a period +------------------------------------------------------- + +CALLING SEQUENCE: + .. 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 status retrieved successfully + * - ``RTEMS_INVALID_ID`` + - invalid rate monotonic period id + * - ``RTEMS_INVALID_ADDRESS`` + - invalid address of status + * - ``RTEMS_NOT_DEFINED`` + - no status is available due to the cpu usage of the task having been + reset since the period initiated + +*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; + uint32_t postponed_jobs_count; + } 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 + since_last_period value contains the elapsed time which has occurred since + the last invocation of the ``rtems_rate_monotonic_period`` directive and + the ``executed_since_last_period`` contains how much processor time the + owning task has consumed since the invocation of the + ``rtems_rate_monotonic_period`` directive. In addition, the + ``postponed_jobs_count value`` contains the count of jobs which are not + released yet. + +NOTES: + This directive will not cause the running task to be preempted. + +.. raw:: latex + + \clearpage + +.. index:: get statistics of period +.. index:: obtain statistics of period +.. index:: rtems_rate_monotonic_get_statistics + +.. _rtems_rate_monotonic_get_statistics: + +RATE_MONOTONIC_GET_STATISTICS - Obtain statistics from a period +--------------------------------------------------------------- + +CALLING SEQUENCE: + .. 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 statistics retrieved 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. + +.. raw:: latex + + \clearpage + +.. index:: reset statistics of period +.. index:: rtems_rate_monotonic_reset_statistics + +.. _rtems_rate_monotonic_reset_statistics: + +RATE_MONOTONIC_RESET_STATISTICS - Reset statistics for a period +--------------------------------------------------------------- + +CALLING SEQUENCE: + .. 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. + +.. raw:: latex + + \clearpage + +.. index:: reset statistics of all periods +.. index:: rtems_rate_monotonic_reset_all_statistics + +.. _rtems_rate_monotonic_reset_all_statistics: + +RATE_MONOTONIC_RESET_ALL_STATISTICS - Reset statistics for all periods +---------------------------------------------------------------------- + +CALLING SEQUENCE: + .. 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. + +.. raw:: latex + + \clearpage + +.. index:: print period statistics report +.. index:: period statistics report +.. index:: rtems_rate_monotonic_report_statistics + +.. _rtems_rate_monotonic_report_statistics: + +RATE_MONOTONIC_REPORT_STATISTICS - Print period statistics report +----------------------------------------------------------------- + +CALLING SEQUENCE: + .. 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. diff --git a/c-user/rate-monotonic/index.rst b/c-user/rate-monotonic/index.rst new file mode 100644 index 0000000..44a5765 --- /dev/null +++ b/c-user/rate-monotonic/index.rst @@ -0,0 +1,16 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + +.. index:: rate mononitonic tasks +.. index:: periodic tasks + +Rate Monotonic Manager +********************** + +.. toctree:: + + introduction + background + operations + directives diff --git a/c-user/rate-monotonic/introduction.rst b/c-user/rate-monotonic/introduction.rst new file mode 100644 index 0000000..cb09898 --- /dev/null +++ b/c-user/rate-monotonic/introduction.rst @@ -0,0 +1,33 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) +.. Copyright (C) 2017 Kuan-Hsun Chen. + +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: + +- :ref:`rtems_rate_monotonic_create` + +- :ref:`rtems_rate_monotonic_ident` + +- :ref:`rtems_rate_monotonic_cancel` + +- :ref:`rtems_rate_monotonic_delete` + +- :ref:`rtems_rate_monotonic_period` + +- :ref:`rtems_rate_monotonic_get_status` + +- :ref:`rtems_rate_monotonic_get_statistics` + +- :ref:`rtems_rate_monotonic_reset_statistics` + +- :ref:`rtems_rate_monotonic_reset_all_statistics` + +- :ref:`rtems_rate_monotonic_report_statistics` diff --git a/c-user/rate-monotonic/operations.rst b/c-user/rate-monotonic/operations.rst new file mode 100644 index 0000000..d7a91b1 --- /dev/null +++ b/c-user/rate-monotonic/operations.rst @@ -0,0 +1,200 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) +.. Copyright (C) 2017 Kuan-Hsun Chen. + +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 postponed job will be released + until there is no more postponed jobs. The calling task returns immediately + with a timeout error status. In the watchdog routine, the period will still + be updated periodically and track the count of the postponed jobs :cite:`Chen:2016:Overrun`. + Please note, the count of the postponed jobs is only saturated until 0xffffffff. + +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_SUCCESSFUL ) { + printf( "rtems_monotonic_create failed with status of %d.\n", status ); + 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_SUCCESSFUL ) { + printf( "rtems_rate_monotonic_delete failed with status of %d.\n", status ); + exit( 1 ); + } + status = rtems_task_delete( RTEMS_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; + 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 ) == RTEMS_TIMEOUT ) + break; + if ( rtems_rate_monotonic_period( period_2, 40 ) == RTEMS_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 ) == RTEMS_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, RTEMS_PERIOD_STATUS ) == RTEMS_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 ) rtems_task_delete( RTEMS_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. diff --git a/c-user/rate_monotonic_manager.rst b/c-user/rate_monotonic_manager.rst deleted file mode 100644 index e9241bc..0000000 --- a/c-user/rate_monotonic_manager.rst +++ /dev/null @@ -1,1091 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-4.0 - -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) -.. Copyright (C) 2017 Kuan-Hsun Chen. - -.. index:: rate mononitonic tasks -.. index:: periodic tasks - -Rate Monotonic Manager -********************** - -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. - -.. index:: periodic task, definition - -Periodicity Definitions ----------------------------------- - -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. - -.. index:: Rate Monotonic Scheduling Algorithm, definition -.. index:: RMS Algorithm, definition - -Rate Monotonic Scheduling Algorithm ------------------------------------ - -The Rate Monotonic Scheduling Algorithm (RMS) is important to real-time systems -designers because it allows one to sufficiently guarantee that a set of tasks -is schedulable (see :cite:`Liu:1973:Scheduling`, :cite:`Lehoczky:1989:RM`, -:cite:`Sha:1990:Ada`, :cite:`Burns:1991:Review`). - -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 fixed-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 -fixed-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. - -.. index:: RMS schedulability analysis - -Schedulability Analysis ------------------------ - -RMS allows application designers to ensure that tasks can meet all deadlines under fixed-priority assignment, -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. - -.. index:: RMS Processor Utilization Rule - -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(i) -/ Period(i)``. The processor utilization can be calculated as follows -where n is the number of tasks in the set being analyzed: - -.. math:: - - Utilization = \sum_{i=1}^{n} Time_i/Period_i - -To ensure schedulability even under transient overload, the processor -utilization must adhere to the following rule: - -.. math:: - - maximumUtilization = n * (2^{\frac{1}{n}} - 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. -See more detail in :cite:`Liu:1973:Scheduling`. - -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. - -.. index:: RMS First Deadline Rule - -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. -See more detail in :cite:`Lehoczky:1989:RM`. - -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. - -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 postponed job will be released - until there is no more postponed jobs. The calling task returns immediately - with a timeout error status. In the watchdog routine, the period will still - be updated periodically and track the count of the postponed jobs :cite:`Chen:2016:Overrun`. - Please note, the count of the postponed jobs is only saturated until 0xffffffff. - -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_SUCCESSFUL ) { - printf( "rtems_monotonic_create failed with status of %d.\n", status ); - 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_SUCCESSFUL ) { - printf( "rtems_rate_monotonic_delete failed with status of %d.\n", status ); - exit( 1 ); - } - status = rtems_task_delete( RTEMS_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; - 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 ) == RTEMS_TIMEOUT ) - break; - if ( rtems_rate_monotonic_period( period_2, 40 ) == RTEMS_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 ) == RTEMS_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, RTEMS_PERIOD_STATUS ) == RTEMS_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 ) rtems_task_delete( RTEMS_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. - -.. raw:: latex - - \clearpage - -.. index:: create a period -.. index:: rtems_rate_monotonic_create - -.. _rtems_rate_monotonic_create: - -RATE_MONOTONIC_CREATE - Create a rate monotonic period ------------------------------------------------------- - -CALLING SEQUENCE: - .. 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 may cause the calling task to be preempted due to an - obtain and release of the object allocator mutex. - -.. raw:: latex - - \clearpage - -.. index:: get ID of a period -.. index:: obtain ID of a period -.. index:: rtems_rate_monotonic_ident - -.. _rtems_rate_monotonic_ident: - -RATE_MONOTONIC_IDENT - Get ID of a period ------------------------------------------ - -CALLING SEQUENCE: - .. 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. - -.. raw:: latex - - \clearpage - -.. index:: cancel a period -.. index:: rtems_rate_monotonic_cancel - -.. _rtems_rate_monotonic_cancel: - -RATE_MONOTONIC_CANCEL - Cancel a period ---------------------------------------- - -CALLING SEQUENCE: - .. 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. - -.. raw:: latex - - \clearpage - -.. index:: rtems_rate_monotonic_delete -.. index:: delete a period - -.. _rtems_rate_monotonic_delete: - -RATE_MONOTONIC_DELETE - Delete a rate monotonic period ------------------------------------------------------- - -CALLING SEQUENCE: - .. 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 may cause the calling task to be preempted due to an - obtain and release of the object allocator mutex. - - A rate monotonic period can be deleted by a task other than the task which - created the period. - -.. raw:: latex - - \clearpage - -.. index:: conclude current period -.. index:: start current period -.. index:: period initiation -.. index:: rtems_rate_monotonic_period - -.. _rtems_rate_monotonic_period: - -RATE_MONOTONIC_PERIOD - Conclude current/Start next period ----------------------------------------------------------- - -CALLING SEQUENCE: - .. 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 id has expired its period, the postponed job will be released immediately - and the following calls of this directive will release postponed - jobs until there is no more deadline miss. - - 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. - -.. raw:: latex - - \clearpage - -.. index:: get status of period -.. index:: obtain status of period -.. index:: rtems_rate_monotonic_get_status - -.. _rtems_rate_monotonic_get_status: - -RATE_MONOTONIC_GET_STATUS - Obtain status from a period -------------------------------------------------------- - -CALLING SEQUENCE: - .. 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 status retrieved successfully - * - ``RTEMS_INVALID_ID`` - - invalid rate monotonic period id - * - ``RTEMS_INVALID_ADDRESS`` - - invalid address of status - * - ``RTEMS_NOT_DEFINED`` - - no status is available due to the cpu usage of the task having been - reset since the period initiated - -*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; - uint32_t postponed_jobs_count; - } 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 - since_last_period value contains the elapsed time which has occurred since - the last invocation of the ``rtems_rate_monotonic_period`` directive and - the ``executed_since_last_period`` contains how much processor time the - owning task has consumed since the invocation of the - ``rtems_rate_monotonic_period`` directive. In addition, the - ``postponed_jobs_count value`` contains the count of jobs which are not - released yet. - -NOTES: - This directive will not cause the running task to be preempted. - -.. raw:: latex - - \clearpage - -.. index:: get statistics of period -.. index:: obtain statistics of period -.. index:: rtems_rate_monotonic_get_statistics - -.. _rtems_rate_monotonic_get_statistics: - -RATE_MONOTONIC_GET_STATISTICS - Obtain statistics from a period ---------------------------------------------------------------- - -CALLING SEQUENCE: - .. 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 statistics retrieved 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. - -.. raw:: latex - - \clearpage - -.. index:: reset statistics of period -.. index:: rtems_rate_monotonic_reset_statistics - -.. _rtems_rate_monotonic_reset_statistics: - -RATE_MONOTONIC_RESET_STATISTICS - Reset statistics for a period ---------------------------------------------------------------- - -CALLING SEQUENCE: - .. 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. - -.. raw:: latex - - \clearpage - -.. index:: reset statistics of all periods -.. index:: rtems_rate_monotonic_reset_all_statistics - -.. _rtems_rate_monotonic_reset_all_statistics: - -RATE_MONOTONIC_RESET_ALL_STATISTICS - Reset statistics for all periods ----------------------------------------------------------------------- - -CALLING SEQUENCE: - .. 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. - -.. raw:: latex - - \clearpage - -.. index:: print period statistics report -.. index:: period statistics report -.. index:: rtems_rate_monotonic_report_statistics - -.. _rtems_rate_monotonic_report_statistics: - -RATE_MONOTONIC_REPORT_STATISTICS - Print period statistics report ------------------------------------------------------------------ - -CALLING SEQUENCE: - .. 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. |