[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