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.hu...@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@rtems.org > http://lists.rtems.org/mailman/listinfo/devel _______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel