[PATCH] c-user: Generate Timer Manager documentation

Gedare Bloom gedare at rtems.org
Wed Dec 2 17:46:11 UTC 2020


Looks good to me.

On Wed, Dec 2, 2020 at 1:26 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.
> ---
>
> The generated documentation is available here:
>
> https://ftp.rtems.org/pub/rtems/people/sebh/c-user.pdf
>
>  c-user/timer/directives.rst   | 992 +++++++++++++++++++++-------------
>  c-user/timer/introduction.rst |  57 +-
>  2 files changed, 674 insertions(+), 375 deletions(-)
>
> diff --git a/c-user/timer/directives.rst b/c-user/timer/directives.rst
> index d9b9877..d65f263 100644
> --- a/c-user/timer/directives.rst
> +++ b/c-user/timer/directives.rst
> @@ -1,463 +1,729 @@
>  .. SPDX-License-Identifier: CC-BY-SA-4.0
>
> +.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de
> )
>  .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation
> (OAR)
>
> +.. 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://docs.rtems.org/branches/master/user/support/bugs.html
> +..
> +.. For information on updating and regenerating please refer to:
> +..
> +.. https://docs.rtems.org/branches/master/eng/req/howto.html
> +
> +.. _TimerManagerDirectives:
> +
>  Directives
>  ==========
>
> -This section details the timer 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 Timer 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/timer/if/create
>
>  .. raw:: latex
>
> -   \clearpage
> +    \clearpage
> +
> +.. index:: rtems_timer_create()
>  .. index:: create a timer
> -.. index:: rtems_timer_create
>
> -.. _rtems_timer_create:
> +.. _InterfaceRtemsTimerCreate:
>
> -TIMER_CREATE - Create a timer
> ------------------------------
> +rtems_timer_create()
> +--------------------
> +
> +Creates a timer.
> +
> +.. rubric:: CALLING SEQUENCE:
> +
> +.. code-block:: c
> +
> +    rtems_status_code rtems_timer_create( rtems_name name, rtems_id *id );
> +
> +.. rubric:: PARAMETERS:
> +
> +``name``
> +    This parameter is the name of the timer.
> +
> +``id``
> +    This parameter is the pointer to an object identifier variable.  The
> +    identifier of the created timer object will be stored in this
> variable, in
> +    case of a successful operation.
> +
> +.. rubric:: DESCRIPTION:
>
> -CALLING SEQUENCE:
> -    .. code-block:: c
> -
> -        rtems_status_code rtems_timer_create(
> -            rtems_name  name,
> -            rtems_id   *id
> -        );
> -
> -DIRECTIVE STATUS CODES:
> -    .. list-table::
> -     :class: rtems-table
> -
> -     * - ``RTEMS_SUCCESSFUL``
> -       - timer created successfully
> -     * - ``RTEMS_INVALID_ADDRESS``
> -       - ``id`` is NULL
> -     * - ``RTEMS_INVALID_NAME``
> -       - invalid timer name
> -     * - ``RTEMS_TOO_MANY``
> -       - too many timers created
> -
> -DESCRIPTION:
> -    This directive creates a timer.  The assigned timer id is returned in
> id.
> -    This id is used to access the timer with other timer manager
> directives.
> -    For control and maintenance of the timer, RTEMS allocates a TMCB from
> the
> -    local TMCB free pool and initializes it.
> -
> -NOTES:
> -    This directive will obtain the allocator mutex and may cause the
> calling
> -    task to be preempted.
> -
> -    In SMP configurations, the processor of the currently executing thread
> -    determines the processor used for the created timer.  During the
> life-time
> -    of the timer this processor is used to manage the timer internally.
> +This directive creates a timer.  The assigned object identifier is
> returned in
> +``id``.  This identifier is used to access the timer with other timer
> related
> +directives.
> +
> +.. rubric:: RETURN VALUES:
> +
> +:c:macro:`RTEMS_SUCCESSFUL`
> +    The requested operation was successful.
> +
> +:c:macro:`RTEMS_INVALID_NAME`
> +    The timer name was invalid.
> +
> +:c:macro:`RTEMS_INVALID_ADDRESS`
> +    The ``id`` parameter was `NULL
> +    <https://en.cppreference.com/w/c/types/NULL>`_.
> +
> +:c:macro:`RTEMS_TOO_MANY`
> +    There was no inactive object available to create a new timer.  The
> number
> +    of timers available to the application is configured through the
> +    :ref:`CONFIGURE_MAXIMUM_TIMERS` configuration option.
> +
> +.. rubric:: 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 timer, RTEMS allocates a :term:`TMCB`
> from
> +the local TMCB free pool and initializes it.
> +
> +In SMP configurations, the processor of the currently executing thread
> +determines the processor used for the created timer.  During the
> life-time of
> +the timer this processor is used to manage the timer internally.
> +
> +.. Generated from spec:/rtems/timer/if/ident
>
>  .. raw:: latex
>
> -   \clearpage
> +    \clearpage
>
> +.. index:: rtems_timer_ident()
>  .. index:: obtain the ID of a timer
> -.. index:: rtems_timer_ident
>
> -.. _rtems_timer_ident:
> +.. _InterfaceRtemsTimerIdent:
>
> -TIMER_IDENT - Get ID of a timer
> --------------------------------
> +rtems_timer_ident()
> +-------------------
> +
> +Identifies a timer by the object name.
>
> -CALLING SEQUENCE:
> -    .. code-block:: c
> +.. rubric:: CALLING SEQUENCE:
>
> -        rtems_status_code rtems_timer_ident(
> -            rtems_name  name,
> -            rtems_id   *id
> -        );
> +.. code-block:: c
>
> -DIRECTIVE STATUS CODES:
> -    .. list-table::
> -     :class: rtems-table
> +    rtems_status_code rtems_timer_ident( rtems_name name, rtems_id *id );
>
> -     * - ``RTEMS_SUCCESSFUL``
> -       - timer identified successfully
> -     * - ``RTEMS_INVALID_ADDRESS``
> -       - ``id`` is NULL
> -     * - ``RTEMS_INVALID_NAME``
> -       - timer name not found
> +.. rubric:: PARAMETERS:
>
> -DESCRIPTION:
> -    This directive obtains the timer id associated with the timer name to
> be
> -    acquired.  If the timer name is not unique, then the timer id will
> match
> -    one of the timers with that name.  However, this timer id is not
> guaranteed
> -    to correspond to the desired timer.  The timer id is used to access
> this
> -    timer in other timer related directives.
> +``name``
> +    This parameter is the object name to look up.
>
> -NOTES:
> -    This directive will not cause the running task to be preempted.
> +``id``
> +    This parameter is the pointer to an object identifier variable.  The
> object
> +    identifier of an object with the specified name will be stored in this
> +    variable, in case of a successful operation.
> +
> +.. rubric:: DESCRIPTION:
> +
> +This directive obtains the timer identifier associated with the timer 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 timer name is not unique, then the timer identifier will match the
> first
> +timer with that name in the search order.  However, this timer identifier
> is
> +not guaranteed to correspond to the desired timer.  The timer identifier
> is
> +used with other timer related directives to access the timer.
> +
> +The objects are searched from lowest to the highest index.  Only the
> local node
> +is searched.
> +
> +.. Generated from spec:/rtems/timer/if/cancel
>
>  .. raw:: latex
>
> -   \clearpage
> +    \clearpage
>
> +.. index:: rtems_timer_cancel()
>  .. index:: cancel a timer
> -.. index:: rtems_timer_cancel
>
> -.. _rtems_timer_cancel:
> +.. _InterfaceRtemsTimerCancel:
>
> -TIMER_CANCEL - Cancel a timer
> ------------------------------
> +rtems_timer_cancel()
> +--------------------
>
> -CALLING SEQUENCE:
> -    .. code-block:: c
> +Cancels the timer.
>
> -        rtems_status_code rtems_timer_cancel(
> -            rtems_id id
> -        );
> +.. rubric:: CALLING SEQUENCE:
>
> -DIRECTIVE STATUS CODES:
> -    .. list-table::
> -     :class: rtems-table
> +.. code-block:: c
>
> -     * - ``RTEMS_SUCCESSFUL``
> -       - timer canceled successfully
> -     * - ``RTEMS_INVALID_ID``
> -       - invalid timer id
> +    rtems_status_code rtems_timer_cancel( rtems_id id );
>
> -DESCRIPTION:
> -    This directive cancels the timer id.  This timer will be reinitiated
> by the
> -    next invocation of ``rtems_timer_reset``, ``rtems_timer_fire_after``,
> or
> -    ``rtems_timer_fire_when`` with this id.
> +.. rubric:: PARAMETERS:
>
> -NOTES:
> -    This directive will not cause the running task to be preempted.
> +``id``
> +    This parameter is the timer identifier.
> +
> +.. rubric:: DESCRIPTION:
> +
> +This directive cancels the timer specified in the ``id`` parameter.  This
> timer
> +will be reinitiated by the next invocation of
> :ref:`InterfaceRtemsTimerReset`,
> +:ref:`InterfaceRtemsTimerFireAfter`, or
> :ref:`InterfaceRtemsTimerFireWhen` with
> +the same timer identifier.
> +
> +.. rubric:: RETURN VALUES:
> +
> +:c:macro:`RTEMS_SUCCESSFUL`
> +    The requested operation was successful.
> +
> +:c:macro:`RTEMS_INVALID_ID`
> +    There was no timer associated with the identifier specified by ``id``.
> +
> +.. rubric:: NOTES:
> +
> +This directive will not cause the running task to be preempted.
> +
> +.. Generated from spec:/rtems/timer/if/delete
>
>  .. raw:: latex
>
> -   \clearpage
> +    \clearpage
>
> +.. index:: rtems_timer_delete()
>  .. index:: delete a timer
> -.. index:: rtems_timer_delete
>
> -.. _rtems_timer_delete:
> +.. _InterfaceRtemsTimerDelete:
>
> -TIMER_DELETE - Delete a timer
> ------------------------------
> +rtems_timer_delete()
> +--------------------
> +
> +Deletes the timer.
> +
> +.. rubric:: CALLING SEQUENCE:
> +
> +.. code-block:: c
>
> -CALLING SEQUENCE:
> -    .. code-block:: c
> +    rtems_status_code rtems_timer_delete( rtems_id id );
>
> -        rtems_status_code rtems_timer_delete(
> -            rtems_id id
> -        );
> +.. rubric:: PARAMETERS:
>
> -DIRECTIVE STATUS CODES:
> -    .. list-table::
> -     :class: rtems-table
> +``id``
> +    This parameter is the timer identifier.
>
> -     * - ``RTEMS_SUCCESSFUL``
> -       - timer deleted successfully
> -     * - ``RTEMS_INVALID_ID``
> -       - invalid timer id
> +.. rubric:: DESCRIPTION:
>
> -DESCRIPTION:
> -    This directive deletes the timer specified by id.  If the timer is
> running,
> -    it is automatically canceled.  The TMCB for the deleted timer is
> reclaimed
> -    by RTEMS.
> +This directive deletes the timer specified by the ``id`` parameter.  If
> the
> +timer is running, it is automatically canceled.
>
> -NOTES:
> -    This directive will obtain the allocator mutex and may cause the
> calling
> -    task to be preempted.
> +.. rubric:: RETURN VALUES:
>
> -    A timer can be deleted by a task other than the task which created the
> -    timer.
> +:c:macro:`RTEMS_SUCCESSFUL`
> +    The requested operation was successful.
> +
> +:c:macro:`RTEMS_INVALID_ID`
> +    There was no timer associated with the identifier specified by ``id``.
> +
> +.. rubric:: NOTES:
> +
> +This directive may cause the calling task to be preempted due to an
> obtain and
> +release of the object allocator mutex.
> +
> +The :term:`TMCB` for the deleted timer is reclaimed by RTEMS.
> +
> +A timer can be deleted by a task other than the task which created the
> timer.
> +
> +.. Generated from spec:/rtems/timer/if/fire-after
>
>  .. raw:: latex
>
> -   \clearpage
> +    \clearpage
>
> +.. index:: rtems_timer_fire_after()
>  .. index:: fire a timer after an interval
> -.. index:: rtems_timer_fire_after
> -
> -.. _rtems_timer_fire_after:
> -
> -TIMER_FIRE_AFTER - Fire timer after interval
> ---------------------------------------------
> -
> -CALLING SEQUENCE:
> -    .. code-block:: c
> -
> -        rtems_status_code rtems_timer_fire_after(
> -            rtems_id                           id,
> -            rtems_interval                     ticks,
> -            rtems_timer_service_routine_entry  routine,
> -            void                              *user_data
> -        );
> -
> -DIRECTIVE STATUS CODES:
> -    .. list-table::
> -     :class: rtems-table
> -
> -     * - ``RTEMS_SUCCESSFUL``
> -       - timer initiated successfully
> -     * - ``RTEMS_INVALID_ADDRESS``
> -       - ``routine`` is NULL
> -     * - ``RTEMS_INVALID_ID``
> -       - invalid timer id
> -     * - ``RTEMS_INVALID_NUMBER``
> -       - invalid interval
> -
> -DESCRIPTION:
> -    This directive initiates the timer specified by id.  If the timer is
> -    running, it is automatically canceled before being initiated.  The
> timer is
> -    scheduled to fire after an interval ticks clock ticks has passed.
> When the
> -    timer fires, the timer service routine routine will be invoked with
> the
> -    argument user_data.
> -
> -NOTES:
> -    This directive will not cause the running task to be preempted.
> +
> +.. _InterfaceRtemsTimerFireAfter:
> +
> +rtems_timer_fire_after()
> +------------------------
> +
> +Fires the timer after the interval.
> +
> +.. rubric:: CALLING SEQUENCE:
> +
> +.. code-block:: c
> +
> +    rtems_status_code rtems_timer_fire_after(
> +      rtems_id                          id,
> +      rtems_interval                    ticks,
> +      rtems_timer_service_routine_entry routine,
> +      void                             *user_data
> +    );
> +
> +.. rubric:: PARAMETERS:
> +
> +``id``
> +    This parameter is the timer identifier.
> +
> +``ticks``
> +    This parameter is the interval until the routine is fired in clock
> ticks.
> +
> +``routine``
> +    This parameter is the routine to schedule.
> +
> +``user_data``
> +    This parameter is the argument passed to the routine when it is fired.
> +
> +.. rubric:: DESCRIPTION:
> +
> +This directive initiates the timer specified by ``id``.  If the timer is
> +running, it is automatically canceled before being initiated.  The timer
> is
> +scheduled to fire after an interval of clock ticks has passed specified by
> +``ticks``.  When the timer fires, the timer service routine ``routine``
> will be
> +invoked with the argument ``user_data`` in the context of the clock tick
> +:term:`ISR`.
> +
> +.. rubric:: RETURN VALUES:
> +
> +:c:macro:`RTEMS_SUCCESSFUL`
> +    The requested operation was successful.
> +
> +:c:macro:`RTEMS_INVALID_NUMBER`
> +    The ``ticks`` parameter was 0.
> +
> +:c:macro:`RTEMS_INVALID_ADDRESS`
> +    The ``routine`` parameter was `NULL
> +    <https://en.cppreference.com/w/c/types/NULL>`_.
> +
> +:c:macro:`RTEMS_INVALID_ID`
> +    There was no timer associated with the identifier specified by ``id``.
> +
> +.. rubric:: NOTES:
> +
> +This directive will not cause the running task to be preempted.
> +
> +.. Generated from spec:/rtems/timer/if/fire-when
>
>  .. raw:: latex
>
> -   \clearpage
> -
> -.. index:: fire a timer at wall time
> -.. index:: rtems_timer_fire_when
> -
> -.. _rtems_timer_fire_when:
> -
> -TIMER_FIRE_WHEN - Fire timer when specified
> --------------------------------------------
> -
> -CALLING SEQUENCE:
> -    .. code-block:: c
> -
> -        rtems_status_code rtems_timer_fire_when(
> -            rtems_id                           id,
> -            rtems_time_of_day                 *wall_time,
> -            rtems_timer_service_routine_entry  routine,
> -            void                              *user_data
> -        );
> -
> -DIRECTIVE STATUS CODES:
> -    .. list-table::
> -     :class: rtems-table
> -
> -     * - ``RTEMS_SUCCESSFUL``
> -       - timer initiated successfully
> -     * - ``RTEMS_INVALID_ADDRESS``
> -       - ``routine`` is NULL
> -     * - ``RTEMS_INVALID_ADDRESS``
> -       - ``wall_time`` is NULL
> -     * - ``RTEMS_INVALID_ID``
> -       - invalid timer id
> -     * - ``RTEMS_NOT_DEFINED``
> -       - system date and time is not set
> -     * - ``RTEMS_INVALID_CLOCK``
> -       - invalid time of day
> -
> -DESCRIPTION:
> -    This directive initiates the timer specified by id.  If the timer is
> -    running, it is automatically canceled before being initiated.  The
> timer is
> -    scheduled to fire at the time of day specified by wall_time.  When the
> -    timer fires, the timer service routine routine will be invoked with
> the
> -    argument user_data.
> -
> -NOTES:
> -    This directive will not cause the running task to be preempted.
> +    \clearpage
> +
> +.. index:: rtems_timer_fire_when()
> +.. index:: fire a timer at time of day
> +
> +.. _InterfaceRtemsTimerFireWhen:
> +
> +rtems_timer_fire_when()
> +-----------------------
> +
> +Fires the timer at the time of day.
> +
> +.. rubric:: CALLING SEQUENCE:
> +
> +.. code-block:: c
> +
> +    rtems_status_code rtems_timer_fire_when(
> +      rtems_id                          id,
> +      rtems_time_of_day                *wall_time,
> +      rtems_timer_service_routine_entry routine,
> +      void                             *user_data
> +    );
> +
> +.. rubric:: PARAMETERS:
> +
> +``id``
> +    This parameter is the timer identifier.
> +
> +``wall_time``
> +    This parameter is the time of day when the routine is fired.
> +
> +``routine``
> +    This parameter is the routine to schedule.
> +
> +``user_data``
> +    This parameter is the argument passed to the routine when it is fired.
> +
> +.. rubric:: DESCRIPTION:
> +
> +This directive initiates the timer specified by ``id``.  If the timer is
> +running, it is automatically canceled before being initiated.  The timer
> is
> +scheduled to fire at the time of day specified by ``wall_time``.  When the
> +timer fires, the timer service routine ``routine`` will be invoked with
> the
> +argument ``user_data`` in the context of the clock tick :term:`ISR`.
> +
> +.. rubric:: RETURN VALUES:
> +
> +:c:macro:`RTEMS_SUCCESSFUL`
> +    The requested operation was successful.
> +
> +:c:macro:`RTEMS_NOT_DEFINED`
> +    The system date and time was not set.
> +
> +:c:macro:`RTEMS_INVALID_ADDRESS`
> +    The ``routine`` parameter was `NULL
> +    <https://en.cppreference.com/w/c/types/NULL>`_.
> +
> +:c:macro:`RTEMS_INVALID_ADDRESS`
> +    The ``wall_time`` parameter was `NULL
> +    <https://en.cppreference.com/w/c/types/NULL>`_.
> +
> +:c:macro:`RTEMS_INVALID_CLOCK`
> +    The time of day was invalid.
> +
> +:c:macro:`RTEMS_INVALID_ID`
> +    There was no timer associated with the identifier specified by ``id``.
> +
> +.. rubric:: NOTES:
> +
> +This directive will not cause the running task to be preempted.
> +
> +.. Generated from spec:/rtems/timer/if/initiate-server
>
>  .. raw:: latex
>
> -   \clearpage
> +    \clearpage
>
> +.. index:: rtems_timer_initiate_server()
>  .. index:: initiate the Timer Server
> -.. index:: rtems_timer_initiate_server
>
> -.. _rtems_timer_initiate_server:
> +.. _InterfaceRtemsTimerInitiateServer:
> +
> +rtems_timer_initiate_server()
> +-----------------------------
> +
> +Initiates the Timer Server.
> +
> +.. rubric:: CALLING SEQUENCE:
> +
> +.. code-block:: c
> +
> +    rtems_status_code rtems_timer_initiate_server(
> +      rtems_task_priority priority,
> +      size_t              stack_size,
> +      rtems_attribute     attribute_set
> +    );
> +
> +.. rubric:: PARAMETERS:
> +
> +``priority``
> +    This parameter is the task priority.
> +
> +``stack_size``
> +    This parameter is the task stack size in bytes.
>
> -TIMER_INITIATE_SERVER - Initiate server for task-based timers
> --------------------------------------------------------------
> +``attribute_set``
> +    This parameter is the task attribute set.
>
> -CALLING SEQUENCE:
> -    .. code-block:: c
> +.. rubric:: DESCRIPTION:
>
> -        rtems_status_code rtems_timer_initiate_server(
> -            uint32_t         priority,
> -            uint32_t         stack_size,
> -            rtems_attribute  attribute_set
> -        );
> +This directive initiates the Timer Server task.  This task is responsible
> for
> +executing all timers initiated via the
> +:ref:`InterfaceRtemsTimerServerFireAfter` or
> +:ref:`InterfaceRtemsTimerServerFireWhen` directives.
>
> -DIRECTIVE STATUS CODES:
> -    .. list-table::
> -     :class: rtems-table
> +.. rubric:: RETURN VALUES:
>
> -     * - ``RTEMS_SUCCESSFUL``
> -       - Timer Server initiated successfully
> -     * - ``RTEMS_TOO_MANY``
> -       - too many tasks created
> +:c:macro:`RTEMS_SUCCESSFUL`
> +    The requested operation was successful.
>
> -DESCRIPTION:
> -    This directive initiates the Timer Server task.  This task is
> responsible
> -    for executing all timers initiated via the
> -    ``rtems_timer_server_fire_after`` or ``rtems_timer_server_fire_when``
> -    directives.
> +:c:macro:`RTEMS_INCORRECT_STATE`
> +    The Timer Server was already initiated.
>
> -NOTES:
> -    This directive could cause the calling task to be preempted.
> +:c:macro:`RTEMS_INVALID_PRIORITY`
> +    The task priority was invalid.
>
> -    The Timer Server task is created using the ``rtems_task_create``
> service
> -    and must be accounted for when configuring the system.
> +:c:macro:`RTEMS_TOO_MANY`
> +    There was no inactive task object available to create the Timer Server
> +    task.
>
> -    Even through this directive invokes the ``rtems_task_create`` and
> -    ``rtems_task_start`` directives, it should only fail due to resource
> -    allocation problems.
> +:c:macro:`RTEMS_UNSATISFIED`
> +    There was not enough memory to allocate the task storage area.  The
> task
> +    storage area contains the task stack, the thread-local storage, and
> the
> +    floating point context.
> +
> +:c:macro:`RTEMS_UNSATISFIED`
> +    One of the task create extensions failed to create the Timer Server
> task.
> +
> +.. rubric:: NOTES:
> +
> +This directive may cause the calling task to be preempted due to an
> obtain and
> +release of the object allocator mutex.
> +
> +The Timer Server task is created using the :ref:`InterfaceRtemsTaskCreate`
> +directive and must be accounted for when configuring the system.
> +
> +.. Generated from spec:/rtems/timer/if/server-fire-after
>
>  .. raw:: latex
>
> -   \clearpage
> +    \clearpage
>
> +.. index:: rtems_timer_server_fire_after()
>  .. index:: fire task-based a timer after an interval
> -.. index:: rtems_timer_server_fire_after
> -
> -.. _rtems_timer_server_fire_after:
> -
> -TIMER_SERVER_FIRE_AFTER - Fire task-based timer after interval
> ---------------------------------------------------------------
> -
> -CALLING SEQUENCE:
> -    .. code-block:: c
> -
> -        rtems_status_code rtems_timer_server_fire_after(
> -            rtems_id                           id,
> -            rtems_interval                     ticks,
> -            rtems_timer_service_routine_entry  routine,
> -            void                              *user_data
> -        );
> -
> -DIRECTIVE STATUS CODES:
> -    .. list-table::
> -     :class: rtems-table
> -
> -     * - ``RTEMS_SUCCESSFUL``
> -       - timer initiated successfully
> -     * - ``RTEMS_INVALID_ADDRESS``
> -       - ``routine`` is NULL
> -     * - ``RTEMS_INVALID_ID``
> -       - invalid timer id
> -     * - ``RTEMS_INVALID_NUMBER``
> -       - invalid interval
> -     * - ``RTEMS_INCORRECT_STATE``
> -       - Timer Server not initiated
> -
> -DESCRIPTION:
> -    This directive initiates the timer specified by id and specifies that
> when
> -    it fires it will be executed by the Timer Server.
> -
> -    If the timer is running, it is automatically canceled before being
> -    initiated.  The timer is scheduled to fire after an interval ticks
> clock
> -    ticks has passed.  When the timer fires, the timer service routine
> routine
> -    will be invoked with the argument user_data.
> -
> -NOTES:
> -    This directive will not cause the running task to be preempted.
> +
> +.. _InterfaceRtemsTimerServerFireAfter:
> +
> +rtems_timer_server_fire_after()
> +-------------------------------
> +
> +Fires the timer after the interval using the Timer Server.
> +
> +.. rubric:: CALLING SEQUENCE:
> +
> +.. code-block:: c
> +
> +    rtems_status_code rtems_timer_server_fire_after(
> +      rtems_id                          id,
> +      rtems_interval                    ticks,
> +      rtems_timer_service_routine_entry routine,
> +      void                             *user_data
> +    );
> +
> +.. rubric:: PARAMETERS:
> +
> +``id``
> +    This parameter is the timer identifier.
> +
> +``ticks``
> +    This parameter is the interval until the routine is fired in clock
> ticks.
> +
> +``routine``
> +    This parameter is the routine to schedule.
> +
> +``user_data``
> +    This parameter is the argument passed to the routine when it is fired.
> +
> +.. rubric:: DESCRIPTION:
> +
> +This directive initiates the timer specified by ``id``.  If the timer is
> +running, it is automatically canceled before being initiated.  The timer
> is
> +scheduled to fire after an interval of clock ticks has passed specified by
> +``ticks``.  When the timer fires, the timer service routine ``routine``
> will be
> +invoked with the argument ``user_data`` in the context of the Timer Server
> +task.
> +
> +.. rubric:: RETURN VALUES:
> +
> +:c:macro:`RTEMS_SUCCESSFUL`
> +    The requested operation was successful.
> +
> +:c:macro:`RTEMS_INCORRECT_STATE`
> +    The Timer Server was not initiated.
> +
> +:c:macro:`RTEMS_INVALID_NUMBER`
> +    The ``ticks`` parameter was 0.
> +
> +:c:macro:`RTEMS_INVALID_ADDRESS`
> +    The ``routine`` parameter was `NULL
> +    <https://en.cppreference.com/w/c/types/NULL>`_.
> +
> +:c:macro:`RTEMS_INVALID_ID`
> +    There was no timer associated with the identifier specified by ``id``.
> +
> +.. rubric:: NOTES:
> +
> +This directive will not cause the running task to be preempted.
> +
> +.. Generated from spec:/rtems/timer/if/server-fire-when
>
>  .. raw:: latex
>
> -   \clearpage
> -
> -.. index:: fire a task-based timer at wall time
> -.. index:: rtems_timer_server_fire_when
> -
> -.. _rtems_timer_server_fire_when:
> -
> -TIMER_SERVER_FIRE_WHEN - Fire task-based timer when specified
> --------------------------------------------------------------
> -
> -CALLING SEQUENCE:
> -    .. code-block:: c
> -
> -        rtems_status_code rtems_timer_server_fire_when(
> -            rtems_id                           id,
> -            rtems_time_of_day                 *wall_time,
> -            rtems_timer_service_routine_entry  routine,
> -            void                              *user_data
> -        );
> -
> -DIRECTIVE STATUS CODES:
> -    .. list-table::
> -     :class: rtems-table
> -
> -     * - ``RTEMS_SUCCESSFUL``
> -       - timer initiated successfully
> -     * - ``RTEMS_INVALID_ADDRESS``
> -       - ``routine`` is NULL
> -     * - ``RTEMS_INVALID_ADDRESS``
> -       - ``wall_time`` is NULL
> -     * - ``RTEMS_INVALID_ID``
> -       - invalid timer id
> -     * - ``RTEMS_NOT_DEFINED``
> -       - system date and time is not set
> -     * - ``RTEMS_INVALID_CLOCK``
> -       - invalid time of day
> -     * - ``RTEMS_INCORRECT_STATE``
> -       - Timer Server not initiated
> -
> -DESCRIPTION:
> -    This directive initiates the timer specified by id and specifies that
> when
> -    it fires it will be executed by the Timer Server.
> -
> -    If the timer is running, it is automatically canceled before being
> -    initiated.  The timer is scheduled to fire at the time of day
> specified by
> -    wall_time.  When the timer fires, the timer service routine routine
> will be
> -    invoked with the argument user_data.
> -
> -NOTES:
> -    This directive will not cause the running task to be preempted.
> +    \clearpage
> +
> +.. index:: rtems_timer_server_fire_when()
> +.. index:: fire a task-based timer at time of day
> +
> +.. _InterfaceRtemsTimerServerFireWhen:
> +
> +rtems_timer_server_fire_when()
> +------------------------------
> +
> +Fires the timer at the time of day using the Timer Server.
> +
> +.. rubric:: CALLING SEQUENCE:
> +
> +.. code-block:: c
> +
> +    rtems_status_code rtems_timer_server_fire_when(
> +      rtems_id                          id,
> +      rtems_time_of_day                *wall_time,
> +      rtems_timer_service_routine_entry routine,
> +      void                             *user_data
> +    );
> +
> +.. rubric:: PARAMETERS:
> +
> +``id``
> +    This parameter is the timer identifier.
> +
> +``wall_time``
> +    This parameter is the time of day when the routine is fired.
> +
> +``routine``
> +    This parameter is the routine to schedule.
> +
> +``user_data``
> +    This parameter is the argument passed to the routine when it is fired.
> +
> +.. rubric:: DESCRIPTION:
> +
> +This directive initiates the timer specified by ``id``.  If the timer is
> +running, it is automatically canceled before being initiated.  The timer
> is
> +scheduled to fire at the time of day specified by ``wall_time``.  When the
> +timer fires, the timer service routine ``routine`` will be invoked with
> the
> +argument ``user_data`` in the context of the Timer Server task.
> +
> +.. rubric:: RETURN VALUES:
> +
> +:c:macro:`RTEMS_SUCCESSFUL`
> +    The requested operation was successful.
> +
> +:c:macro:`RTEMS_INCORRECT_STATE`
> +    The Timer Server was not initiated.
> +
> +:c:macro:`RTEMS_NOT_DEFINED`
> +    The system date and time was not set.
> +
> +:c:macro:`RTEMS_INVALID_ADDRESS`
> +    The ``routine`` parameter was `NULL
> +    <https://en.cppreference.com/w/c/types/NULL>`_.
> +
> +:c:macro:`RTEMS_INVALID_ADDRESS`
> +    The ``wall_time`` parameter was `NULL
> +    <https://en.cppreference.com/w/c/types/NULL>`_.
> +
> +:c:macro:`RTEMS_INVALID_CLOCK`
> +    The time of day was invalid.
> +
> +:c:macro:`RTEMS_INVALID_ID`
> +    There was no timer associated with the identifier specified by ``id``.
> +
> +.. rubric:: NOTES:
> +
> +This directive will not cause the running task to be preempted.
> +
> +.. Generated from spec:/rtems/timer/if/reset
>
>  .. raw:: latex
>
> -   \clearpage
> +    \clearpage
>
> +.. index:: rtems_timer_reset()
>  .. index:: reset a timer
> -.. index:: rtems_timer_reset
>
> -.. _rtems_timer_reset:
> +.. _InterfaceRtemsTimerReset:
> +
> +rtems_timer_reset()
> +-------------------
> +
> +Resets the timer.
> +
> +.. rubric:: CALLING SEQUENCE:
> +
> +.. code-block:: c
> +
> +    rtems_status_code rtems_timer_reset( rtems_id id );
> +
> +.. rubric:: PARAMETERS:
> +
> +``id``
> +    This parameter is the timer identifier.
> +
> +.. rubric:: DESCRIPTION:
> +
> +This directive resets the timer specified by ``id``.  This timer must
> have been
> +previously initiated with either the :ref:`InterfaceRtemsTimerFireAfter`
> or
> +:ref:`InterfaceRtemsTimerServerFireAfter` directive.  If active the timer
> is
> +canceled, after which the timer is reinitiated using the same interval and
> +timer service routine which the original
> :ref:`InterfaceRtemsTimerFireAfter` or
> +:ref:`InterfaceRtemsTimerServerFireAfter` directive used.
> +
> +.. rubric:: RETURN VALUES:
> +
> +:c:macro:`RTEMS_SUCCESSFUL`
> +    The requested operation was successful.
> +
> +:c:macro:`RTEMS_INVALID_ID`
> +    There was no timer associated with the identifier specified by ``id``.
> +
> +:c:macro:`RTEMS_NOT_DEFINED`
> +    The timer was not of the interval class.
> +
> +.. rubric:: NOTES:
> +
> +This directive will not cause the running task to be preempted.
> +
> +If the timer has not been used or the last usage of this timer was by a
> +:ref:`InterfaceRtemsTimerFireWhen` or
> :ref:`InterfaceRtemsTimerServerFireWhen`
> +directive, then the :c:macro:`RTEMS_NOT_DEFINED` error is returned.
> +
> +Restarting a cancelled after timer results in the timer being reinitiated
> with
> +its previous timer service routine and interval.
> +
> +.. Generated from spec:/rtems/timer/if/get-information
> +
> +.. raw:: latex
> +
> +    \clearpage
> +
> +.. index:: rtems_timer_get_information()
> +
> +.. _InterfaceRtemsTimerGetInformation:
> +
> +rtems_timer_get_information()
> +-----------------------------
> +
> +Gets information about the timer.
> +
> +.. rubric:: CALLING SEQUENCE:
> +
> +.. code-block:: c
> +
> +    rtems_status_code rtems_timer_get_information(
> +      rtems_id                 id,
> +      rtems_timer_information *the_info
> +    );
> +
> +.. rubric:: PARAMETERS:
> +
> +``id``
> +    This parameter is the timer identifier.
>
> -TIMER_RESET - Reset an interval timer
> --------------------------------------
> +``the_info``
> +    This parameter is the pointer to a timer information variable.  The
> +    information about the timer will be stored in this variable, in case
> of a
> +    successful operation.
>
> -CALLING SEQUENCE:
> -    .. code-block:: c
> +.. rubric:: DESCRIPTION:
>
> -        rtems_status_code rtems_timer_reset(
> -            rtems_id   id
> -        );
> +This directive returns information about the timer.
>
> -DIRECTIVE STATUS CODES:
> -    .. list-table::
> -     :class: rtems-table
> +.. rubric:: RETURN VALUES:
>
> -     * - ``RTEMS_SUCCESSFUL``
> -       - timer reset successfully
> -     * - ``RTEMS_INVALID_ID``
> -       - invalid timer id
> -     * - ``RTEMS_NOT_DEFINED``
> -       - attempted to reset a when or newly created timer
> +:c:macro:`RTEMS_SUCCESSFUL`
> +    The requested operation was successful.
>
> -DESCRIPTION:
> -    This directive resets the timer associated with id.  This timer must
> have
> -    been previously initiated with either the ``rtems_timer_fire_after``
> or
> -    ``rtems_timer_server_fire_after`` directive.  If active the timer is
> -    canceled, after which the timer is reinitiated using the same
> interval and
> -    timer service routine which the original ``rtems_timer_fire_after`` or
> -    ``rtems_timer_server_fire_after`` directive used.
> +:c:macro:`RTEMS_INVALID_ADDRESS`
> +    The ``the_info`` parameter was `NULL
> +    <https://en.cppreference.com/w/c/types/NULL>`_.
>
> -NOTES:
> -    If the timer has not been used or the last usage of this timer was by
> a
> -    ``rtems_timer_fire_when`` or ``rtems_timer_server_fire_when``
> directive,
> -    then the ``RTEMS_NOT_DEFINED`` error is returned.
> +:c:macro:`RTEMS_INVALID_ID`
> +    There was no timer associated with the identifier specified by ``id``.
>
> -    Restarting a cancelled after timer results in the timer being
> reinitiated
> -    with its previous timer service routine and interval.
> +.. rubric:: NOTES:
>
> -    This directive will not cause the running task to be preempted.
> +This directive will not cause the running task to be preempted.
> diff --git a/c-user/timer/introduction.rst b/c-user/timer/introduction.rst
> index 48a36ba..78f6c67 100644
> --- a/c-user/timer/introduction.rst
> +++ b/c-user/timer/introduction.rst
> @@ -1,29 +1,62 @@
>  .. SPDX-License-Identifier: CC-BY-SA-4.0
>
> +.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de
> )
>  .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation
> (OAR)
>
> +.. 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://docs.rtems.org/branches/master/user/support/bugs.html
> +..
> +.. For information on updating and regenerating please refer to:
> +..
> +.. https://docs.rtems.org/branches/master/eng/req/howto.html
> +
> +.. Generated from spec:/rtems/timer/if/group
> +
> +.. _TimerManagerIntroduction:
> +
>  Introduction
>  ============
>
> -The timer manager provides support for timer
> -facilities.  The directives provided by the timer manager are:
> +.. The following list was generated from:
> +.. spec:/rtems/timer/if/create
> +.. spec:/rtems/timer/if/ident
> +.. spec:/rtems/timer/if/cancel
> +.. spec:/rtems/timer/if/delete
> +.. spec:/rtems/timer/if/fire-after
> +.. spec:/rtems/timer/if/fire-when
> +.. spec:/rtems/timer/if/initiate-server
> +.. spec:/rtems/timer/if/server-fire-after
> +.. spec:/rtems/timer/if/server-fire-when
> +.. spec:/rtems/timer/if/reset
> +.. spec:/rtems/timer/if/get-information
> +
> +The Timer Manager provides support for timer facilities. The directives
> +provided by the Timer Manager are:
> +
> +* :ref:`InterfaceRtemsTimerCreate` - Creates a timer.
>
> -- :ref:`rtems_timer_create`
> +* :ref:`InterfaceRtemsTimerIdent` - Identifies a timer by the object name.
>
> -- :ref:`rtems_timer_ident`
> +* :ref:`InterfaceRtemsTimerCancel` - Cancels the timer.
>
> -- :ref:`rtems_timer_cancel`
> +* :ref:`InterfaceRtemsTimerDelete` - Deletes the timer.
>
> -- :ref:`rtems_timer_delete`
> +* :ref:`InterfaceRtemsTimerFireAfter` - Fires the timer after the
> interval.
>
> -- :ref:`rtems_timer_fire_after`
> +* :ref:`InterfaceRtemsTimerFireWhen` - Fires the timer at the time of day.
>
> -- :ref:`rtems_timer_fire_when`
> +* :ref:`InterfaceRtemsTimerInitiateServer` - Initiates the Timer Server.
>
> -- :ref:`rtems_timer_initiate_server`
> +* :ref:`InterfaceRtemsTimerServerFireAfter` - Fires the timer after the
> +  interval using the Timer Server.
>
> -- :ref:`rtems_timer_server_fire_after`
> +* :ref:`InterfaceRtemsTimerServerFireWhen` - Fires the timer at the time
> of day
> +  using the Timer Server.
>
> -- :ref:`rtems_timer_server_fire_when`
> +* :ref:`InterfaceRtemsTimerReset` - Resets the timer.
>
> -- :ref:`rtems_timer_reset`
> +* :ref:`InterfaceRtemsTimerGetInformation` - Gets information about the
> timer.
> --
> 2.26.2
>
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rtems.org/pipermail/devel/attachments/20201202/5080c914/attachment-0001.html>


More information about the devel mailing list