c-user: Split up rate-monotonic manager

This makes it easier to automatically generate parts of the manager
documentation in the future.

Update #3993.

1 files changed, 474 insertions, 0 deletions

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.