[PATCH 10/16] c-user: Split up rate-monotonic manager
Sebastian Huber
sebastian.huber at embedded-brains.de
Thu Aug 20 10:18:59 UTC 2020
This makes it easier to automatically generate parts of the manager
documentation in the future.
Update #3993.
---
c-user/index.rst | 2 +-
c-user/rate_monotonic_manager.rst | 1091 -----------------------------
c-user/ratemon/background.rst | 390 +++++++++++
c-user/ratemon/directives.rst | 474 +++++++++++++
c-user/ratemon/index.rst | 16 +
c-user/ratemon/introduction.rst | 33 +
c-user/ratemon/operations.rst | 200 ++++++
7 files changed, 1114 insertions(+), 1092 deletions(-)
delete mode 100644 c-user/rate_monotonic_manager.rst
create mode 100644 c-user/ratemon/background.rst
create mode 100644 c-user/ratemon/directives.rst
create mode 100644 c-user/ratemon/index.rst
create mode 100644 c-user/ratemon/introduction.rst
create mode 100644 c-user/ratemon/operations.rst
diff --git a/c-user/index.rst b/c-user/index.rst
index f28fd6b..7d72e30 100644
--- a/c-user/index.rst
+++ b/c-user/index.rst
@@ -34,7 +34,7 @@ RTEMS Classic API Guide (|version|).
intr/index
clock/index
timer_manager
- rate_monotonic_manager
+ ratemon/index
sem/index
barrier/index
message/index
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.
diff --git a/c-user/ratemon/background.rst b/c-user/ratemon/background.rst
new file mode 100644
index 0000000..9ca7dff
--- /dev/null
+++ b/c-user/ratemon/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/ratemon/directives.rst b/c-user/ratemon/directives.rst
new file mode 100644
index 0000000..d100c81
--- /dev/null
+++ b/c-user/ratemon/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/ratemon/index.rst b/c-user/ratemon/index.rst
new file mode 100644
index 0000000..44a5765
--- /dev/null
+++ b/c-user/ratemon/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/ratemon/introduction.rst b/c-user/ratemon/introduction.rst
new file mode 100644
index 0000000..cb09898
--- /dev/null
+++ b/c-user/ratemon/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/ratemon/operations.rst b/c-user/ratemon/operations.rst
new file mode 100644
index 0000000..d7a91b1
--- /dev/null
+++ b/c-user/ratemon/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.
--
2.26.2
More information about the devel
mailing list