diff options
Diffstat (limited to 'c-user/timer/directives.rst')
| -rw-r--r-- | c-user/timer/directives.rst | 231 |
1 files changed, 173 insertions, 58 deletions
diff --git a/c-user/timer/directives.rst b/c-user/timer/directives.rst index d65f263..2237b30 100644 --- a/c-user/timer/directives.rst +++ b/c-user/timer/directives.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) .. This file is part of the RTEMS quality process and was automatically @@ -8,11 +8,15 @@ .. 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 +.. https://www.rtems.org/bugs.html .. -.. For information on updating and regenerating please refer to: +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: .. -.. https://docs.rtems.org/branches/master/eng/req/howto.html +.. https://docs.rtems.org .. _TimerManagerDirectives: @@ -48,18 +52,19 @@ Creates a timer. .. rubric:: PARAMETERS: ``name`` - This parameter is the name of the timer. + This parameter is the object 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. + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the identifier of the created timer will + be stored in this object. .. rubric:: DESCRIPTION: -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. +This directive creates a timer which resides on the local node. The timer has +the user-defined object name specified in ``name``. The assigned object +identifier is returned in ``id``. This identifier is used to access the timer +with other timer related directives. .. rubric:: RETURN VALUES: @@ -67,28 +72,42 @@ directives. The requested operation was successful. :c:macro:`RTEMS_INVALID_NAME` - The timer name was invalid. + The ``name`` parameter 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. + There was no inactive object available to create a timer. The number of + timers available to the application is configured through the + :ref:`CONFIGURE_MAXIMUM_TIMERS` application 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. +The processor used to maintain the timer is the processor of the calling task +at some point during the timer creation. 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. +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. + +* The number of timers available to the application is configured through the + :ref:`CONFIGURE_MAXIMUM_TIMERS` application configuration option. + +* Where the object class corresponding to the directive is configured to use + unlimited objects, the directive may allocate memory from the RTEMS + Workspace. .. Generated from spec:/rtems/timer/if/ident @@ -118,13 +137,13 @@ Identifies a timer by the object name. This parameter is the object name to look up. ``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. + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the object identifier of an object with + the specified name will be stored in this object. .. rubric:: DESCRIPTION: -This directive obtains the timer identifier associated with the timer name +This directive obtains a timer identifier associated with the timer name specified in ``name``. .. rubric:: RETURN VALUES: @@ -146,12 +165,22 @@ specified in ``name``. 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. +not guaranteed to correspond to the desired timer. The objects are searched from lowest to the highest index. Only the local node is searched. +The timer identifier is used with other timer related directives to access the +timer. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + .. Generated from spec:/rtems/timer/if/cancel .. raw:: latex @@ -181,10 +210,11 @@ Cancels the timer. .. 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. +This directive cancels the timer specified by ``id``. This timer will be +reinitiated by the next invocation of :ref:`InterfaceRtemsTimerReset`, +:ref:`InterfaceRtemsTimerFireAfter`, :ref:`InterfaceRtemsTimerFireWhen`, +:ref:`InterfaceRtemsTimerServerFireAfter`, or +:ref:`InterfaceRtemsTimerServerFireWhen` with the same timer identifier. .. rubric:: RETURN VALUES: @@ -194,9 +224,17 @@ the same timer identifier. :c:macro:`RTEMS_INVALID_ID` There was no timer associated with the identifier specified by ``id``. -.. rubric:: NOTES: +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. -This directive will not cause the running task to be preempted. +* The directive will not cause the calling task to be preempted. .. Generated from spec:/rtems/timer/if/delete @@ -227,8 +265,8 @@ Deletes the timer. .. rubric:: DESCRIPTION: -This directive deletes the timer specified by the ``id`` parameter. If the -timer is running, it is automatically canceled. +This directive deletes the timer specified by ``id``. If the timer is running, +it is automatically canceled. .. rubric:: RETURN VALUES: @@ -240,12 +278,24 @@ timer is running, it is automatically canceled. .. 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. +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. + +* The calling task does not have to be the task that created the object. Any + local task that knows the object identifier can delete the object. + +* Where the object class corresponding to the directive is configured to use + unlimited objects, the directive may free memory to the RTEMS Workspace. .. Generated from spec:/rtems/timer/if/fire-after @@ -312,9 +362,17 @@ invoked with the argument ``user_data`` in the context of the clock tick :c:macro:`RTEMS_INVALID_ID` There was no timer associated with the identifier specified by ``id``. -.. rubric:: NOTES: +.. rubric:: CONSTRAINTS: -This directive will not cause the running task to be preempted. +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. .. Generated from spec:/rtems/timer/if/fire-when @@ -338,7 +396,7 @@ Fires the timer at the time of day. rtems_status_code rtems_timer_fire_when( rtems_id id, - rtems_time_of_day *wall_time, + const rtems_time_of_day *wall_time, rtems_timer_service_routine_entry routine, void *user_data ); @@ -387,9 +445,17 @@ argument ``user_data`` in the context of the clock tick :term:`ISR`. :c:macro:`RTEMS_INVALID_ID` There was no timer associated with the identifier specified by ``id``. -.. rubric:: NOTES: +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. -This directive will not cause the running task to be preempted. +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. .. Generated from spec:/rtems/timer/if/initiate-server @@ -460,12 +526,27 @@ executing all timers initiated via the .. 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. +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The number of timers available to the application is configured through the + :ref:`CONFIGURE_MAXIMUM_TIMERS` application configuration option. + +* Where the object class corresponding to the directive is configured to use + unlimited objects, the directive may allocate memory from the RTEMS + Workspace. + .. Generated from spec:/rtems/timer/if/server-fire-after .. raw:: latex @@ -534,9 +615,17 @@ task. :c:macro:`RTEMS_INVALID_ID` There was no timer associated with the identifier specified by ``id``. -.. rubric:: NOTES: +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. -This directive will not cause the running task to be preempted. +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. .. Generated from spec:/rtems/timer/if/server-fire-when @@ -560,7 +649,7 @@ Fires the timer at the time of day using the Timer Server. rtems_status_code rtems_timer_server_fire_when( rtems_id id, - rtems_time_of_day *wall_time, + const rtems_time_of_day *wall_time, rtems_timer_service_routine_entry routine, void *user_data ); @@ -612,9 +701,17 @@ argument ``user_data`` in the context of the Timer Server task. :c:macro:`RTEMS_INVALID_ID` There was no timer associated with the identifier specified by ``id``. -.. rubric:: NOTES: +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: -This directive will not cause the running task to be preempted. +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. .. Generated from spec:/rtems/timer/if/reset @@ -665,8 +762,6 @@ timer service routine which the original :ref:`InterfaceRtemsTimerFireAfter` or .. 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. @@ -674,6 +769,18 @@ 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. +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. + .. Generated from spec:/rtems/timer/if/get-information .. raw:: latex @@ -704,9 +811,9 @@ Gets information about the timer. This parameter is the timer identifier. ``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. + This parameter is the pointer to an :ref:`InterfaceRtemsTimerInformation` + object. When the directive call is successful, the information about the + timer will be stored in this object. .. rubric:: DESCRIPTION: @@ -724,6 +831,14 @@ This directive returns information about the timer. :c:macro:`RTEMS_INVALID_ID` There was no timer associated with the identifier specified by ``id``. -.. rubric:: NOTES: +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. -This directive will not cause the running task to be preempted. +* The directive will not cause the calling task to be preempted. |