Looks good to me. On Wed, Dec 2, 2020 at 1:26 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. > --- > > 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@rtems.org > http://lists.rtems.org/mailman/listinfo/devel >
_______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
