diff options
Diffstat (limited to 'c-user/event/directives.rst')
| -rw-r--r-- | c-user/event/directives.rst | 70 |
1 files changed, 49 insertions, 21 deletions
diff --git a/c-user/event/directives.rst b/c-user/event/directives.rst index 59e4d2c..04a2894 100644 --- a/c-user/event/directives.rst +++ b/c-user/event/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 .. _EventManagerDirectives: @@ -76,7 +80,7 @@ situations applies: The requested operation was successful. :c:macro:`RTEMS_INVALID_ID` - There was no task with the specified identifier. + There was no task associated with the identifier specified by ``id``. .. rubric:: NOTES: @@ -101,6 +105,19 @@ Sending an event set to a global task which does not reside on the local node will generate a request telling the remote node to send the event set to the appropriate task. +.. 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 may unblock a task. This may cause the calling task to be + preempted. + .. Generated from spec:/rtems/event/if/receive .. raw:: latex @@ -156,33 +173,37 @@ This directive can be used to To **get the pending events** use the constant :c:macro:`RTEMS_PENDING_EVENTS` for the ``event_in`` parameter. The pending events are returned to the calling -task but the event set of the task is left unaltered. The ``option_set`` and -``ticks`` parameters are ignored in this case. The directive returns -immediately and does not block. +task but the event set of the calling task is left unaltered. The +``option_set`` and ``ticks`` parameters are ignored in this case. The +directive returns immediately and does not block. To **receive events** you have to define an input event condition and some -options. The **option set** specified in ``option_set`` defines +options. -* if the task will wait or poll for the events, and +The **option set** specified in ``option_set`` is built through a *bitwise or* +of the option constants described below. Not all combinations of options are +allowed. Some options are mutually exclusive. If mutually exclusive options +are combined, the behaviour is undefined. Options not mentioned below are not +evaluated by this directive and have no effect. Default options can be selected +by using the :c:macro:`RTEMS_DEFAULT_OPTIONS` constant. The option set defines -* if the task wants to receive all or any of the input events. +* if the calling task will wait or poll for the events, and -The option set is built through a *bitwise or* of the option constants -described below. +* if the calling task wants to receive all or any of the input events. -The task can **wait** or **poll** for the events. +The calling task can **wait** or **poll** for the events. * **Waiting** for events is the default and can be emphasized through the use of the :c:macro:`RTEMS_WAIT` option. The ``ticks`` parameter defines how - long the task is willing to wait. Use :c:macro:`RTEMS_NO_TIMEOUT` to wait - potentially forever, otherwise set a timeout interval in clock ticks. + long the calling task is willing to wait. Use :c:macro:`RTEMS_NO_TIMEOUT` to + wait potentially forever, otherwise set a timeout interval in clock ticks. * Not waiting for events (**polling**) is selected by the :c:macro:`RTEMS_NO_WAIT` option. If this option is defined, then the ``ticks`` parameter is ignored. -The task can receive **all** or **any** of the input events specified in -``event_in``. +The calling task can receive **all** or **any** of the input events specified +in ``event_in``. * Receiving **all** input events is the default and can be emphasized through the use of the :c:macro:`RTEMS_EVENT_ALL` option. @@ -208,9 +229,6 @@ The task can receive **all** or **any** of the input events specified in .. rubric:: NOTES: -This directive shall be called by a task. Calling this directive from -interrupt context is undefined behaviour. - This directive only affects the events specified in ``event_in``. Any pending events that do not correspond to any of the events specified in ``event_in`` will be left pending. @@ -225,3 +243,13 @@ bitwise or of the :c:macro:`RTEMS_NO_WAIT` and :c:macro:`RTEMS_EVENT_ANY` options for the ``option_set`` parameter. The pending events are returned and the event set of the task is cleared. If no events are pending then the :c:macro:`RTEMS_UNSATISFIED` status code will be returned. + +.. 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 timeout functionality of the directive requires a :term:`clock tick`. |