[PATCH 1/2] c-user: Generate rate-monotonic manager docs

Gedare Bloom gedare at rtems.org
Thu Apr 22 15:46:58 UTC 2021


this one is fine, if you want to resend separately I can ACK it right
away, or resend with the v2 of the message queue is fine with me.

On Thu, Apr 22, 2021 at 8:07 AM Sebastian Huber
<sebastian.huber at embedded-brains.de> wrote:
>
> The documentation is a consolidation of the comments in Doxygen markup
> and the documentation sources in Sphinx markup.  The documentation was
> transfered to interface specification items.  The documentation source
> files were generated from the items by a script.
>
> Update #3993.
> ---
>  c-user/rate-monotonic/directives.rst   | 949 ++++++++++++++++---------
>  c-user/rate-monotonic/introduction.rst |  71 +-
>  2 files changed, 654 insertions(+), 366 deletions(-)
>
> diff --git a/c-user/rate-monotonic/directives.rst b/c-user/rate-monotonic/directives.rst
> index d100c81..1935e8a 100644
> --- a/c-user/rate-monotonic/directives.rst
> +++ b/c-user/rate-monotonic/directives.rst
> @@ -1,474 +1,719 @@
>  .. SPDX-License-Identifier: CC-BY-SA-4.0
>
> +.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de)
> +.. Copyright (C) 2017 Kuan-Hsun Chen
>  .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
> -.. Copyright (C) 2017 Kuan-Hsun Chen.
> +
> +.. This file is part of the RTEMS quality process and was automatically
> +.. generated.  If you find something that needs to be fixed or
> +.. worded better please post a report or patch to an RTEMS mailing list
> +.. or raise a bug report:
> +..
> +.. https://www.rtems.org/bugs.html
> +..
> +.. For information on updating and regenerating please refer to the How-To
> +.. section in the Software Requirements Engineering chapter of the
> +.. RTEMS Software Engineering manual.  The manual is provided as a part of
> +.. a release.  For development sources please refer to the online
> +.. documentation at:
> +..
> +.. https://docs.rtems.org
> +
> +.. _RateMonotonicManagerDirectives:
>
>  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.
> +This section details the directives of the Rate-Monotonic Manager. A subsection
> +is dedicated to each of this manager's directives and lists the calling
> +sequence, parameters, description, return values, and notes of the directive.
> +
> +.. Generated from spec:/rtems/ratemon/if/create
>
>  .. raw:: latex
>
> -   \clearpage
> +    \clearpage
>
> +.. index:: rtems_rate_monotonic_create()
>  .. index:: create a period
> -.. index:: rtems_rate_monotonic_create
>
> -.. _rtems_rate_monotonic_create:
> +.. _InterfaceRtemsRateMonotonicCreate:
> +
> +rtems_rate_monotonic_create()
> +-----------------------------
> +
> +Creates a period.
> +
> +.. rubric:: CALLING SEQUENCE:
> +
> +.. code-block:: c
> +
> +    rtems_status_code rtems_rate_monotonic_create( rtems_name name, rtems_id *id );
> +
> +.. rubric:: PARAMETERS:
> +
> +``name``
> +    This parameter is the object name of the period.
> +
> +``id``
> +    This parameter is the pointer to an object identifier variable.  When the
> +    directive call is successful, the identifier of the created period will be
> +    stored in this variable.
> +
> +.. rubric:: DESCRIPTION:
> +
> +This directive creates a period which resides on the local node.  The period
> +has the user-defined object name specified in ``name`` The assigned object
> +identifier is returned in ``id``.  This identifier is used to access the period
> +with other rate monotonic related directives.
>
> -RATE_MONOTONIC_CREATE - Create a rate monotonic period
> -------------------------------------------------------
> +.. rubric:: RETURN VALUES:
>
> -CALLING SEQUENCE:
> -    .. code-block:: c
> +:c:macro:`RTEMS_SUCCESSFUL`
> +    The requested operation was successful.
>
> -        rtems_status_code rtems_rate_monotonic_create(
> -            rtems_name  name,
> -            rtems_id   *id
> -        );
> +:c:macro:`RTEMS_INVALID_NAME`
> +    The ``name`` parameter was invalid.
>
> -DIRECTIVE STATUS CODES:
> -    .. list-table::
> -     :class: rtems-table
> +:c:macro:`RTEMS_TOO_MANY`
> +    There was no inactive object available to create a period.  The number of
> +    periods available to the application is configured through the
> +    :ref:`CONFIGURE_MAXIMUM_PERIODS` application configuration option.
>
> -     * - ``RTEMS_SUCCESSFUL``
> -       - rate monotonic period created successfully
> -     * - ``RTEMS_INVALID_NAME``
> -       - invalid period name
> -     * - ``RTEMS_TOO_MANY``
> -       - too many periods created
> +.. rubric:: NOTES:
>
> -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.
> +The calling task is registered as the owner of the created period.  Some
> +directives can be only used by this task for the created period.
>
> -NOTES:
> -    This directive may cause the calling task to be preempted due to an
> -    obtain and release of the object allocator mutex.
> +For control and maintenance of the period, RTEMS allocates a :term:`PCB` from
> +the local PCB free pool and initializes it.
> +
> +.. rubric:: CONSTRAINTS:
> +
> +The following constraints apply to this directive:
> +
> +* The directive may be called from within device driver initialization context.
> +
> +* The directive may be called from within task context.
> +
> +* The directive may obtain and release the object allocator mutex.  This may
> +  cause the calling task to be preempted.
> +
> +* The number of periods available to the application is configured through the
> +  :ref:`CONFIGURE_MAXIMUM_PERIODS` application configuration option.
> +
> +* Where the object class corresponding to the directive is configured to use
> +  unlimited objects, the directive may allocate memory from the RTEMS
> +  Workspace.
> +
> +.. Generated from spec:/rtems/ratemon/if/ident
>
>  .. raw:: latex
>
> -   \clearpage
> +    \clearpage
> +
> +.. index:: rtems_rate_monotonic_ident()
> +
> +.. _InterfaceRtemsRateMonotonicIdent:
> +
> +rtems_rate_monotonic_ident()
> +----------------------------
>
> -.. index:: get ID of a period
> -.. index:: obtain ID of a period
> -.. index:: rtems_rate_monotonic_ident
> +Identifies a period by the object name.
>
> -.. _rtems_rate_monotonic_ident:
> +.. rubric:: CALLING SEQUENCE:
>
> -RATE_MONOTONIC_IDENT - Get ID of a period
> ------------------------------------------
> +.. code-block:: c
>
> -CALLING SEQUENCE:
> -    .. code-block:: c
> +    rtems_status_code rtems_rate_monotonic_ident( rtems_name name, rtems_id *id );
>
> -        rtems_status_code rtems_rate_monotonic_ident(
> -            rtems_name  name,
> -            rtems_id   *id
> -        );
> +.. rubric:: PARAMETERS:
>
> -DIRECTIVE STATUS CODES:
> -    .. list-table::
> -     :class: rtems-table
> +``name``
> +    This parameter is the object name to look up.
>
> -     * - ``RTEMS_SUCCESSFUL``
> -       - period identified successfully
> -     * - ``RTEMS_INVALID_NAME``
> -       - period name not found
> +``id``
> +    This parameter is the pointer to an object identifier variable.  When the
> +    directive call is successful, the object identifier of an object with the
> +    specified name will be stored in this variable.
>
> -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.
> +.. rubric:: DESCRIPTION:
>
> -NOTES:
> -    This directive will not cause the running task to be preempted.
> +This directive obtains a period identifier associated with the period name
> +specified in ``name``.
> +
> +.. rubric:: RETURN VALUES:
> +
> +:c:macro:`RTEMS_SUCCESSFUL`
> +    The requested operation was successful.
> +
> +:c:macro:`RTEMS_INVALID_ADDRESS`
> +    The ``id`` parameter was `NULL
> +    <https://en.cppreference.com/w/c/types/NULL>`_.
> +
> +:c:macro:`RTEMS_INVALID_NAME`
> +    The ``name`` parameter was 0.
> +
> +:c:macro:`RTEMS_INVALID_NAME`
> +    There was no object with the specified name on the local node.
> +
> +.. rubric:: NOTES:
> +
> +If the period name is not unique, then the period identifier will match the
> +first period with that name in the search order.  However, this period
> +identifier is not guaranteed to correspond to the desired period.
> +
> +The objects are searched from lowest to the highest index.  Only the local node
> +is searched.
> +
> +The period identifier is used with other rate monotonic related directives to
> +access the period.
> +
> +.. rubric:: CONSTRAINTS:
> +
> +The following constraints apply to this directive:
> +
> +* The directive may be called from within any runtime context.
> +
> +* The directive will not cause the calling task to be preempted.
> +
> +.. Generated from spec:/rtems/ratemon/if/cancel
>
>  .. raw:: latex
>
> -   \clearpage
> +    \clearpage
>
> +.. index:: rtems_rate_monotonic_cancel()
>  .. index:: cancel a period
> -.. index:: rtems_rate_monotonic_cancel
>
> -.. _rtems_rate_monotonic_cancel:
> +.. _InterfaceRtemsRateMonotonicCancel:
>
> -RATE_MONOTONIC_CANCEL - Cancel a period
> ----------------------------------------
> +rtems_rate_monotonic_cancel()
> +-----------------------------
> +
> +Cancels the period.
> +
> +.. rubric:: CALLING SEQUENCE:
> +
> +.. code-block:: c
> +
> +    rtems_status_code rtems_rate_monotonic_cancel( rtems_id id );
> +
> +.. rubric:: PARAMETERS:
> +
> +``id``
> +    This parameter is the rate monotonic period identifier.
> +
> +.. rubric:: DESCRIPTION:
>
> -CALLING SEQUENCE:
> -    .. code-block:: c
> +This directive cancels the rate monotonic period specified by ``id``.  This
> +period may be reinitiated by the next invocation of
> +:ref:`InterfaceRtemsRateMonotonicPeriod`.
>
> -        rtems_status_code rtems_rate_monotonic_cancel(
> -            rtems_id id
> -        );
> +.. rubric:: RETURN VALUES:
>
> -DIRECTIVE STATUS CODES:
> -    .. list-table::
> -     :class: rtems-table
> +:c:macro:`RTEMS_SUCCESSFUL`
> +    The requested operation was successful.
>
> -     * - ``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
> +:c:macro:`RTEMS_INVALID_ID`
> +    There was no rate monotonic period associated with the identifier specified
> +    by ``id``.
>
> -DESCRIPTION:
> +:c:macro:`RTEMS_NOT_OWNER_OF_RESOURCE`
> +    The rate monotonic period was not created by the calling task.
>
> -    This directive cancels the rate monotonic period id.  This period will be
> -    reinitiated by the next invocation of ``rtems_rate_monotonic_period``
> -    with id.
> +.. rubric:: CONSTRAINTS:
>
> -NOTES:
> -    This directive will not cause the running task to be preempted.
> +The following constraints apply to this directive:
>
> -    The rate monotonic period specified by id must have been created by the
> -    calling task.
> +* The directive may be called from within task context.
> +
> +* The directive will not cause the calling task to be preempted.
> +
> +* The directive may be used exclusively by the task which created the
> +  associated object.
> +
> +.. Generated from spec:/rtems/ratemon/if/delete
>
>  .. raw:: latex
>
> -   \clearpage
> +    \clearpage
>
> -.. index:: rtems_rate_monotonic_delete
> +.. index:: rtems_rate_monotonic_delete()
>  .. index:: delete a period
>
> -.. _rtems_rate_monotonic_delete:
> +.. _InterfaceRtemsRateMonotonicDelete:
> +
> +rtems_rate_monotonic_delete()
> +-----------------------------
> +
> +Deletes the period.
> +
> +.. rubric:: CALLING SEQUENCE:
> +
> +.. code-block:: c
> +
> +    rtems_status_code rtems_rate_monotonic_delete( rtems_id id );
> +
> +.. rubric:: PARAMETERS:
> +
> +``id``
> +    This parameter is the period identifier.
> +
> +.. rubric:: DESCRIPTION:
> +
> +This directive deletes the period specified by ``id``.  If the period is
> +running, it is automatically canceled.
>
> -RATE_MONOTONIC_DELETE - Delete a rate monotonic period
> -------------------------------------------------------
> +.. rubric:: RETURN VALUES:
>
> -CALLING SEQUENCE:
> -    .. code-block:: c
> +:c:macro:`RTEMS_SUCCESSFUL`
> +    The requested operation was successful.
>
> -        rtems_status_code rtems_rate_monotonic_delete(
> -            rtems_id id
> -        );
> +:c:macro:`RTEMS_INVALID_ID`
> +    There was no period associated with the identifier specified by ``id``.
>
> -DIRECTIVE STATUS CODES:
> -    .. list-table::
> -     :class: rtems-table
> +.. rubric:: NOTES:
>
> -     * - ``RTEMS_SUCCESSFUL``
> -       - period deleted successfully
> -     * - ``RTEMS_INVALID_ID``
> -       - invalid rate monotonic period id
> +The :term:`PCB` for the deleted period is reclaimed by RTEMS.
>
> -DESCRIPTION:
> +.. rubric:: CONSTRAINTS:
>
> -    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.
> +The following constraints apply to this directive:
>
> -NOTES:
> -    This directive may cause the calling task to be preempted due to an
> -    obtain and release of the object allocator mutex.
> +* The directive may be called from within device driver initialization context.
>
> -    A rate monotonic period can be deleted by a task other than the task which
> -    created the period.
> +* The directive may be called from within task context.
> +
> +* The directive may obtain and release the object allocator mutex.  This may
> +  cause the calling task to be preempted.
> +
> +* The calling task does not have to be the task that created the object.  Any
> +  local task that knows the object identifier can delete the object.
> +
> +* Where the object class corresponding to the directive is configured to use
> +  unlimited objects, the directive may free memory to the RTEMS Workspace.
> +
> +.. Generated from spec:/rtems/ratemon/if/period
>
>  .. raw:: latex
>
> -   \clearpage
> +    \clearpage
>
> +.. index:: rtems_rate_monotonic_period()
>  .. 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.
> +
> +.. _InterfaceRtemsRateMonotonicPeriod:
> +
> +rtems_rate_monotonic_period()
> +-----------------------------
> +
> +Concludes the current period and start the next period, or gets the period
> +status.
> +
> +.. rubric:: CALLING SEQUENCE:
> +
> +.. code-block:: c
> +
> +    rtems_status_code rtems_rate_monotonic_period(
> +      rtems_id       id,
> +      rtems_interval length
> +    );
> +
> +.. rubric:: PARAMETERS:
> +
> +``id``
> +    This parameter is the rate monotonic period identifier.
> +
> +``length``
> +    This parameter is the period length in :term:`clock ticks <clock tick>` or
> +    :c:macro:`RTEMS_PERIOD_STATUS` to get the period status.
> +
> +.. rubric:: DESCRIPTION:
> +
> +This directive initiates the rate monotonic period specified by ``id``  with a
> +length of period ticks specified by ``length``.  If the period is running, then
> +the calling task will block for the remainder of the period before reinitiating
> +the period with the specified period length.  If the period was not running
> +(either expired or never initiated), the period is immediately initiated and
> +the directive returns immediately.  If the period has expired, 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 length of :c:macro:`RTEMS_PERIOD_STATUS` ticks, the
> +current state of the period will be returned.  The directive status indicates
> +the current state of the period.  This does not alter the state or period
> +length of the period.
> +
> +.. rubric:: RETURN VALUES:
> +
> +:c:macro:`RTEMS_SUCCESSFUL`
> +    The requested operation was successful.
> +
> +:c:macro:`RTEMS_INVALID_ID`
> +    There was no rate monotonic period associated with the identifier specified
> +    by ``id``.
> +
> +:c:macro:`RTEMS_NOT_OWNER_OF_RESOURCE`
> +    The rate monotonic period was not created by the calling task.
> +
> +:c:macro:`RTEMS_NOT_DEFINED`
> +    The rate monotonic period has never been initiated (only possible when the
> +    ``length`` parameter was equal to :c:macro:`RTEMS_PERIOD_STATUS`).
> +
> +:c:macro:`RTEMS_TIMEOUT`
> +    The rate monotonic period has expired.
> +
> +.. rubric:: CONSTRAINTS:
> +
> +The following constraints apply to this directive:
> +
> +* The directive may be called from within task context.
> +
> +* The directive may be used exclusively by the task which created the
> +  associated object.
> +
> +.. Generated from spec:/rtems/ratemon/if/get-status
>
>  .. raw:: latex
>
> -   \clearpage
> +    \clearpage
>
> +.. index:: rtems_rate_monotonic_get_status()
>  .. 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.
> +
> +.. _InterfaceRtemsRateMonotonicGetStatus:
> +
> +rtems_rate_monotonic_get_status()
> +---------------------------------
> +
> +Gets the detailed status of the period.
> +
> +.. rubric:: CALLING SEQUENCE:
> +
> +.. code-block:: c
> +
> +    rtems_status_code rtems_rate_monotonic_get_status(
> +      rtems_id                            id,
> +      rtems_rate_monotonic_period_status *status
> +    );
> +
> +.. rubric:: PARAMETERS:
> +
> +``id``
> +    This parameter is the rate monotonic period identifier.
> +
> +``status``
> +    This parameter is the pointer to a
> +    :c:type:`rtems_rate_monotonic_period_status` variable.  When the directive
> +    call is successful, the detailed period status will be stored in this
> +    variable.
> +
> +.. rubric:: DESCRIPTION:
> +
> +This directive returns the detailed status of the rate monotonic period
> +specified by ``id``.  The detailed status of the period will be returned in the
> +members of the period status object referenced by ``status``:
> +
> +* The ``owner`` member is set to the identifier of the owner task of the
> +  period.
> +
> +* The ``state`` member is set to the current state of the period.
> +
> +* The ``postponed_jobs_count`` member is set to the count of jobs which are not
> +  released yet.
> +
> +* If the current state of the period is :c:macro:`RATE_MONOTONIC_INACTIVE`, the
> +  ``since_last_period`` and ``executed_since_last_period`` members will be set
> +  to zero.  Otherwise, both members will contain time information since the
> +  last successful invocation of the :ref:`InterfaceRtemsRateMonotonicPeriod`
> +  directive by the owner task.  More specifically, the ``since_last_period``
> +  member will be set to the time elapsed since the last successful invocation.
> +  The ``executed_since_last_period`` member will be set to the processor time
> +  consumed by the owner task since the last successful invocation.
> +
> +.. rubric:: RETURN VALUES:
> +
> +:c:macro:`RTEMS_SUCCESSFUL`
> +    The requested operation was successful.
> +
> +:c:macro:`RTEMS_INVALID_ID`
> +    There was no rate monotonic period associated with the identifier specified
> +    by ``id``.
> +
> +:c:macro:`RTEMS_INVALID_ADDRESS`
> +    The ``status`` parameter was `NULL
> +    <https://en.cppreference.com/w/c/types/NULL>`_.
> +
> +:c:macro:`RTEMS_NOT_DEFINED`
> +    There was no status available due to a reset of the processor time usage of
> +    the owner task of the period.
> +
> +.. rubric:: CONSTRAINTS:
> +
> +The following constraints apply to this directive:
> +
> +* The directive may be called from within task context.
> +
> +* The directive may be called from within interrupt context.
> +
> +* The directive will not cause the calling task to be preempted.
> +
> +.. Generated from spec:/rtems/ratemon/if/get-statistics
>
>  .. raw:: latex
>
> -   \clearpage
> +    \clearpage
>
> +.. index:: rtems_rate_monotonic_get_statistics()
>  .. 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.
> +
> +.. _InterfaceRtemsRateMonotonicGetStatistics:
> +
> +rtems_rate_monotonic_get_statistics()
> +-------------------------------------
> +
> +Gets the statistics of the period.
> +
> +.. rubric:: CALLING SEQUENCE:
> +
> +.. code-block:: c
> +
> +    rtems_status_code rtems_rate_monotonic_get_statistics(
> +      rtems_id                                id,
> +      rtems_rate_monotonic_period_statistics *status
> +    );
> +
> +.. rubric:: PARAMETERS:
> +
> +``id``
> +    This parameter is the rate monotonic period identifier.
> +
> +``status``
> +    This parameter is the pointer to a
> +    :c:type:`rtems_rate_monotonic_period_statistics` variable.  When the
> +    directive call is successful, the period statistics will be stored in this
> +    variable.
> +
> +.. rubric:: DESCRIPTION:
> +
> +This directive returns the statistics of the rate monotonic period specified by
> +``id``.  The statistics of the period will be returned in the members of the
> +period statistics object referenced by ``status``:
> +
> +* The ``count`` member is set to the number of periods executed.
> +
> +* The ``missed_count`` member is set to the number of periods missed.
> +
> +* The ``min_cpu_time`` member is set to the least amount of processor time used
> +  in the period.
> +
> +* The ``max_cpu_time`` member is set to the highest amount of processor time
> +  used in the period.
> +
> +* The ``total_cpu_time`` member is set to the total amount of processor time
> +  used in the period.
> +
> +* The ``min_wall_time`` member is set to the least amount of
> +  :term:`CLOCK_MONOTONIC` time used in the period.
> +
> +* The ``max_wall_time`` member is set to the highest amount of
> +  :term:`CLOCK_MONOTONIC` time used in the period.
> +
> +* The ``total_wall_time`` member is set to the total amount of
> +  :term:`CLOCK_MONOTONIC` time used in the period.
> +
> +.. rubric:: RETURN VALUES:
> +
> +:c:macro:`RTEMS_SUCCESSFUL`
> +    The requested operation was successful.
> +
> +:c:macro:`RTEMS_INVALID_ID`
> +    There was no rate monotonic period associated with the identifier specified
> +    by ``id``.
> +
> +:c:macro:`RTEMS_INVALID_ADDRESS`
> +    The ``status`` parameter was `NULL
> +    <https://en.cppreference.com/w/c/types/NULL>`_.
> +
> +.. rubric:: CONSTRAINTS:
> +
> +The following constraints apply to this directive:
> +
> +* The directive may be called from within task context.
> +
> +* The directive may be called from within interrupt context.
> +
> +* The directive will not cause the calling task to be preempted.
> +
> +.. Generated from spec:/rtems/ratemon/if/reset-statistics
>
>  .. raw:: latex
>
> -   \clearpage
> +    \clearpage
>
> +.. index:: rtems_rate_monotonic_reset_statistics()
>  .. index:: reset statistics of period
> -.. index:: rtems_rate_monotonic_reset_statistics
>
> -.. _rtems_rate_monotonic_reset_statistics:
> +.. _InterfaceRtemsRateMonotonicResetStatistics:
> +
> +rtems_rate_monotonic_reset_statistics()
> +---------------------------------------
> +
> +Resets the statistics of the period.
> +
> +.. rubric:: CALLING SEQUENCE:
> +
> +.. code-block:: c
> +
> +    rtems_status_code rtems_rate_monotonic_reset_statistics( rtems_id id );
> +
> +.. rubric:: PARAMETERS:
> +
> +``id``
> +    This parameter is the rate monotonic period identifier.
>
> -RATE_MONOTONIC_RESET_STATISTICS - Reset statistics for a period
> ----------------------------------------------------------------
> +.. rubric:: DESCRIPTION:
>
> -CALLING SEQUENCE:
> -    .. code-block:: c
> +This directive resets the statistics of the rate monotonic period specified by
> +``id``.
>
> -        rtems_status_code rtems_rate_monotonic_reset_statistics(
> -            rtems_id  id
> -        );
> +.. rubric:: RETURN VALUES:
>
> -DIRECTIVE STATUS CODES:
> -    .. list-table::
> -     :class: rtems-table
> +:c:macro:`RTEMS_SUCCESSFUL`
> +    The requested operation was successful.
>
> -     * - ``RTEMS_SUCCESSFUL``
> -       - period initiated successfully
> -     * - ``RTEMS_INVALID_ID``
> -       - invalid rate monotonic period id
> +:c:macro:`RTEMS_INVALID_ID`
> +    There was no rate monotonic period associated with the identifier specified
> +    by ``id``.
>
> -DESCRIPTION:
> -    This directive resets the statistics information associated with this rate
> -    monotonic period instance.
> +.. rubric:: CONSTRAINTS:
>
> -NOTES:
> -    This directive will not cause the running task to be preempted.
> +The following constraints apply to this directive:
> +
> +* The directive may be called from within task context.
> +
> +* The directive may be called from within interrupt context.
> +
> +* The directive will not cause the calling task to be preempted.
> +
> +.. Generated from spec:/rtems/ratemon/if/reset-all-statistics
>
>  .. raw:: latex
>
> -   \clearpage
> +    \clearpage
>
> +.. index:: rtems_rate_monotonic_reset_all_statistics()
>  .. index:: reset statistics of all periods
> -.. index:: rtems_rate_monotonic_reset_all_statistics
>
> -.. _rtems_rate_monotonic_reset_all_statistics:
> +.. _InterfaceRtemsRateMonotonicResetAllStatistics:
> +
> +rtems_rate_monotonic_reset_all_statistics()
> +-------------------------------------------
> +
> +Resets the statistics of all periods.
>
> -RATE_MONOTONIC_RESET_ALL_STATISTICS - Reset statistics for all periods
> -----------------------------------------------------------------------
> +.. rubric:: CALLING SEQUENCE:
>
> -CALLING SEQUENCE:
> -    .. code-block:: c
> +.. code-block:: c
>
> -        void rtems_rate_monotonic_reset_all_statistics(void);
> +    void rtems_rate_monotonic_reset_all_statistics( void );
>
> -DIRECTIVE STATUS CODES:
> -    NONE
> +.. rubric:: DESCRIPTION:
>
> -DESCRIPTION:
> -    This directive resets the statistics information associated with all rate
> -    monotonic period instances.
> +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.
> +.. rubric:: CONSTRAINTS:
> +
> +The following constraints apply to this directive:
> +
> +* The directive may be called from within task context.
> +
> +* The directive may obtain and release the object allocator mutex.  This may
> +  cause the calling task to be preempted.
> +
> +.. Generated from spec:/rtems/ratemon/if/report-statistics
>
>  .. raw:: latex
>
> -   \clearpage
> +    \clearpage
>
> +.. index:: rtems_rate_monotonic_report_statistics()
>  .. index:: print period statistics report
>  .. index:: period statistics report
> -.. index:: rtems_rate_monotonic_report_statistics
>
> -.. _rtems_rate_monotonic_report_statistics:
> +.. _InterfaceRtemsRateMonotonicReportStatistics:
> +
> +rtems_rate_monotonic_report_statistics()
> +----------------------------------------
> +
> +Reports the period statistics using the :c:func:`printk` printer.
> +
> +.. rubric:: CALLING SEQUENCE:
> +
> +.. code-block:: c
> +
> +    void rtems_rate_monotonic_report_statistics( void );
> +
> +.. rubric:: DESCRIPTION:
> +
> +This directive prints a report on all active periods which have executed at
> +least one period using the :c:func:`printk` printer.
> +
> +.. rubric:: CONSTRAINTS:
> +
> +The following constraints apply to this directive:
> +
> +* The directive may be called from within task context.
> +
> +* The directive may obtain and release the object allocator mutex.  This may
> +  cause the calling task to be preempted.
> +
> +.. Generated from spec:/rtems/ratemon/if/report-statistics-with-plugin
> +
> +.. raw:: latex
> +
> +    \clearpage
> +
> +.. index:: rtems_rate_monotonic_report_statistics_with_plugin()
> +.. index:: print period statistics report
> +.. index:: period statistics report
> +
> +.. _InterfaceRtemsRateMonotonicReportStatisticsWithPlugin:
> +
> +rtems_rate_monotonic_report_statistics_with_plugin()
> +----------------------------------------------------
> +
> +Reports the period statistics using the printer plugin.
> +
> +.. rubric:: CALLING SEQUENCE:
> +
> +.. code-block:: c
>
> -RATE_MONOTONIC_REPORT_STATISTICS - Print period statistics report
> ------------------------------------------------------------------
> +    void rtems_rate_monotonic_report_statistics_with_plugin(
> +      const struct rtems_printer *printer
> +    );
>
> -CALLING SEQUENCE:
> -    .. code-block:: c
> +.. rubric:: PARAMETERS:
>
> -        void rtems_rate_monotonic_report_statistics(void);
> +``printer``
> +    This parameter is the printer plugin to output the report.
>
> -DIRECTIVE STATUS CODES:
> -    NONE
> +.. rubric:: DESCRIPTION:
>
> -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.
> +This directive prints a report on all active periods which have executed at
> +least one period using the printer plugin specified by ``printer``.
>
> -    .. index:: rtems_rate_monotonic_period_statistics
> +.. rubric:: CONSTRAINTS:
>
> -    .. code-block:: c
> +The following constraints apply to this directive:
>
> -        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
> +* The directive may be called from within task context.
>
> -NOTES:
> -    This directive will not cause the running task to be preempted.
> +* The directive may obtain and release the object allocator mutex.  This may
> +  cause the calling task to be preempted.
> diff --git a/c-user/rate-monotonic/introduction.rst b/c-user/rate-monotonic/introduction.rst
> index cb09898..5b0c094 100644
> --- a/c-user/rate-monotonic/introduction.rst
> +++ b/c-user/rate-monotonic/introduction.rst
> @@ -1,33 +1,76 @@
>  .. SPDX-License-Identifier: CC-BY-SA-4.0
>
> +.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de)
> +.. Copyright (C) 2017 Kuan-Hsun Chen
>  .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
> -.. Copyright (C) 2017 Kuan-Hsun Chen.
> +
> +.. This file is part of the RTEMS quality process and was automatically
> +.. generated.  If you find something that needs to be fixed or
> +.. worded better please post a report or patch to an RTEMS mailing list
> +.. or raise a bug report:
> +..
> +.. https://www.rtems.org/bugs.html
> +..
> +.. For information on updating and regenerating please refer to the How-To
> +.. section in the Software Requirements Engineering chapter of the
> +.. RTEMS Software Engineering manual.  The manual is provided as a part of
> +.. a release.  For development sources please refer to the online
> +.. documentation at:
> +..
> +.. https://docs.rtems.org
> +
> +.. Generated from spec:/rtems/ratemon/if/group
> +
> +.. _RateMonotonicManagerIntroduction:
>
>  Introduction
>  ============
>
> -The rate monotonic manager provides facilities to implement tasks which execute
> +.. The following list was generated from:
> +.. spec:/rtems/ratemon/if/create
> +.. spec:/rtems/ratemon/if/ident
> +.. spec:/rtems/ratemon/if/cancel
> +.. spec:/rtems/ratemon/if/delete
> +.. spec:/rtems/ratemon/if/period
> +.. spec:/rtems/ratemon/if/get-status
> +.. spec:/rtems/ratemon/if/get-statistics
> +.. spec:/rtems/ratemon/if/reset-statistics
> +.. spec:/rtems/ratemon/if/reset-all-statistics
> +.. spec:/rtems/ratemon/if/report-statistics
> +.. spec:/rtems/ratemon/if/report-statistics-with-plugin
> +
> +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:
> +which can be used to analyze and tune the application. The directives provided
> +by the Rate-Monotonic Manager are:
> +
> +* :ref:`InterfaceRtemsRateMonotonicCreate` - Creates a period.
>
> -- :ref:`rtems_rate_monotonic_create`
> +* :ref:`InterfaceRtemsRateMonotonicIdent` - Identifies a period by the object
> +  name.
>
> -- :ref:`rtems_rate_monotonic_ident`
> +* :ref:`InterfaceRtemsRateMonotonicCancel` - Cancels the period.
>
> -- :ref:`rtems_rate_monotonic_cancel`
> +* :ref:`InterfaceRtemsRateMonotonicDelete` - Deletes the period.
>
> -- :ref:`rtems_rate_monotonic_delete`
> +* :ref:`InterfaceRtemsRateMonotonicPeriod` - Concludes the current period and
> +  start the next period, or gets the period status.
>
> -- :ref:`rtems_rate_monotonic_period`
> +* :ref:`InterfaceRtemsRateMonotonicGetStatus` - Gets the detailed status of the
> +  period.
>
> -- :ref:`rtems_rate_monotonic_get_status`
> +* :ref:`InterfaceRtemsRateMonotonicGetStatistics` - Gets the statistics of the
> +  period.
>
> -- :ref:`rtems_rate_monotonic_get_statistics`
> +* :ref:`InterfaceRtemsRateMonotonicResetStatistics` - Resets the statistics of
> +  the period.
>
> -- :ref:`rtems_rate_monotonic_reset_statistics`
> +* :ref:`InterfaceRtemsRateMonotonicResetAllStatistics` - Resets the statistics
> +  of all periods.
>
> -- :ref:`rtems_rate_monotonic_reset_all_statistics`
> +* :ref:`InterfaceRtemsRateMonotonicReportStatistics` - Reports the period
> +  statistics using the :c:func:`printk` printer.
>
> -- :ref:`rtems_rate_monotonic_report_statistics`
> +* :ref:`InterfaceRtemsRateMonotonicReportStatisticsWithPlugin` - Reports the
> +  period statistics using the printer plugin.
> --
> 2.26.2
>
>
>
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel


More information about the devel mailing list