From 775380c5576a0827957d6cfbb796d39d67f66452 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Wed, 20 Jan 2021 13:58:28 +0100 Subject: c-user: Clarify event manager documentation Unify the wording across similar directives of other managers. Add "CONSTRAINTS" section. Update #3993. --- c-user/event/directives.rst | 57 ++++++++++++++++++++++++++++++------------- c-user/event/introduction.rst | 2 +- 2 files changed, 41 insertions(+), 18 deletions(-) (limited to 'c-user') diff --git a/c-user/event/directives.rst b/c-user/event/directives.rst index 1a37313..9d9bfe4 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 (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 @@ -105,6 +105,18 @@ 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 another task which may preempt the calling task. + .. Generated from spec:/rtems/event/if/receive .. raw:: latex @@ -160,33 +172,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. @@ -212,9 +228,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. @@ -229,3 +242,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`. diff --git a/c-user/event/introduction.rst b/c-user/event/introduction.rst index 69a2e7e..2876b2c 100644 --- a/c-user/event/introduction.rst +++ b/c-user/event/introduction.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 (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 -- cgit v1.2.3