diff options
| -rw-r--r-- | c-user/timer/directives.rst | 992 | ||||
| -rw-r--r-- | 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. |