diff options
Diffstat (limited to 'c-user/event')
| -rw-r--r-- | c-user/event/background.rst | 96 | ||||
| -rw-r--r-- | c-user/event/directives.rst | 255 | ||||
| -rw-r--r-- | c-user/event/index.rst | 17 | ||||
| -rw-r--r-- | c-user/event/introduction.rst | 39 | ||||
| -rw-r--r-- | c-user/event/operations.rst | 63 |
5 files changed, 470 insertions, 0 deletions
diff --git a/c-user/event/background.rst b/c-user/event/background.rst new file mode 100644 index 0000000..f14e55f --- /dev/null +++ b/c-user/event/background.rst @@ -0,0 +1,96 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Background +========== + +.. index:: event flag, definition +.. index:: event set, definition +.. index:: rtems_event_set + +Event Sets +---------- + +An event flag is used by a task (or ISR) to inform another task of the +occurrence of a significant situation. Thirty-two event flags are associated +with each task. A collection of one or more event flags is referred to as an +event set. The data type ``rtems_event_set`` is used to manage event sets. + +The application developer should remember the following key characteristics of +event operations when utilizing the event manager: + +- Events provide a simple synchronization facility. + +- Events are aimed at tasks. + +- Tasks can wait on more than one event simultaneously. + +- Events are independent of one another. + +- Events do not hold or transport data. + +- Events are not queued. In other words, if an event is sent more than once to + a task before being received, the second and subsequent send operations to + that same task have no effect. + +An event set is posted when it is directed (or sent) to a task. A pending +event is an event that has been posted but not received. An event condition is +used to specify the event set which the task desires to receive and the +algorithm which will be used to determine when the request is satisfied. An +event condition is satisfied based upon one of two algorithms which are +selected by the user. The ``RTEMS_EVENT_ANY`` algorithm states that an event +condition is satisfied when at least a single requested event is posted. The +``RTEMS_EVENT_ALL`` algorithm states that an event condition is satisfied when +every requested event is posted. + +.. index:: event condition, building +.. index:: event set, building + +Building an Event Set or Condition +---------------------------------- + +An event set or condition is built by a bitwise OR of the desired events. The +set of valid events is ``RTEMS_EVENT_0`` through ``RTEMS_EVENT_31``. If an +event is not explicitly specified in the set or condition, then it is not +present. Events are specifically designed to be mutually exclusive, therefore +bitwise OR and addition operations are equivalent as long as each event appears +exactly once in the event set list. + +For example, when sending the event set consisting of ``RTEMS_EVENT_6``, +``RTEMS_EVENT_15``, and ``RTEMS_EVENT_31``, the event parameter to the +``rtems_event_send`` directive should be ``RTEMS_EVENT_6 | RTEMS_EVENT_15 | +RTEMS_EVENT_31``. + +Building an EVENT_RECEIVE Option Set +------------------------------------ + +In general, an option is built by a bitwise OR of the desired option +components. The set of valid options for the ``rtems_event_receive`` directive +are listed in the following table: + +.. list-table:: + :class: rtems-table + + * - ``RTEMS_WAIT`` + - task will wait for event (default) + * - ``RTEMS_NO_WAIT`` + - task should not wait + * - ``RTEMS_EVENT_ALL`` + - return after all events (default) + * - ``RTEMS_EVENT_ANY`` + - return after any events + +Option values are specifically designed to be mutually exclusive, therefore +bitwise OR and addition operations are equivalent as long as each option +appears exactly once in the component list. An option listed as a default is +not required to appear in the option list, although it is a good programming +practice to specify default options. If all defaults are desired, the option +``RTEMS_DEFAULT_OPTIONS`` should be specified on this call. + +This example demonstrates the option parameter needed to poll for all events in +a particular event condition to arrive. The option parameter passed to the +``rtems_event_receive`` directive should be either ``RTEMS_EVENT_ALL | +RTEMS_NO_WAIT`` or ``RTEMS_NO_WAIT``. The option parameter can be set to +``RTEMS_NO_WAIT`` because ``RTEMS_EVENT_ALL`` is the default condition for +``rtems_event_receive``. diff --git a/c-user/event/directives.rst b/c-user/event/directives.rst new file mode 100644 index 0000000..04a2894 --- /dev/null +++ b/c-user/event/directives.rst @@ -0,0 +1,255 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. 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 +.. 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://www.rtems.org/bugs.html +.. +.. 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 + +.. _EventManagerDirectives: + +Directives +========== + +This section details the directives of the Event 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/event/if/send + +.. raw:: latex + + \clearpage + +.. index:: rtems_event_send() + +.. _InterfaceRtemsEventSend: + +rtems_event_send() +------------------ + +Sends the event set to the task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_event_send( rtems_id id, rtems_event_set event_in ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the identifier of the target task to receive the event + set. + +``event_in`` + This parameter is the event set to send. + +.. rubric:: DESCRIPTION: + +This directive sends the event set, ``event_in``, to the target task identified +by ``id``. Based upon the state of the target task, one of the following +situations applies: + +* The target task is blocked waiting for events, then + + * if the waiting task's input event condition is satisfied, then the task is + made ready for execution, or + + * otherwise, the event set is posted but left pending and the task remains + blocked. + +* The target task is not waiting for events, then the event set is posted and + left pending. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``id``. + +.. rubric:: NOTES: + +Events can be sent by tasks or an :term:`ISR`. + +Specifying :c:macro:`RTEMS_SELF` for ``id`` results in the event set being sent +to the calling task. + +The event set to send shall be built by a *bitwise or* of the desired events. +The set of valid events is :c:macro:`RTEMS_EVENT_0` through +:c:macro:`RTEMS_EVENT_31`. If an event is not explicitly specified in the set, +then it is not present. + +Identical events sent to a task are not queued. In other words, the second, +and subsequent, posting of an event to a task before it can perform an +:ref:`InterfaceRtemsEventReceive` has no effect. + +The calling task will be preempted if it has preemption enabled and a higher +priority task is unblocked as the result of this directive. + +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 + + \clearpage + +.. index:: rtems_event_receive() + +.. _InterfaceRtemsEventReceive: + +rtems_event_receive() +--------------------- + +Receives or gets an event set from the calling task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_event_receive( + rtems_event_set event_in, + rtems_option option_set, + rtems_interval ticks, + rtems_event_set *event_out + ); + +.. rubric:: PARAMETERS: + +``event_in`` + This parameter is the event set of interest. Use + :c:macro:`RTEMS_PENDING_EVENTS` to get the pending events. + +``option_set`` + This parameter is the option set. + +``ticks`` + This parameter is the timeout in clock ticks if the :c:macro:`RTEMS_WAIT` + option is set. Use :c:macro:`RTEMS_NO_TIMEOUT` to wait potentially + forever. + +``event_out`` + This parameter is the pointer to an event set. The received or pending + events are stored in the referenced event set if the operation was + successful. + +.. rubric:: DESCRIPTION: + +This directive can be used to + +* get the pending events of the calling task, or + +* receive events. + +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 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`` 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 calling task will wait or poll for the events, and + +* if the calling task wants to receive all or any of the input 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 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 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. + +* Receiving **any** of the input events is selected by the + :c:macro:`RTEMS_EVENT_ANY` option. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``event_out`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_UNSATISFIED` + The events of interest were not immediately available. + +:c:macro:`RTEMS_TIMEOUT` + The events of interest were not available within the specified timeout + interval. + +.. rubric:: NOTES: + +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. + +To receive all events use the event set constant :c:macro:`RTEMS_ALL_EVENTS` +for the ``event_in`` parameter. Do not confuse this event set constant with +the directive option :c:macro:`RTEMS_EVENT_ALL`. + +A task can **receive all of the pending events** by calling the directive with +a value of :c:macro:`RTEMS_ALL_EVENTS` for the ``event_in`` parameter and the +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/index.rst b/c-user/event/index.rst new file mode 100644 index 0000000..dd926e1 --- /dev/null +++ b/c-user/event/index.rst @@ -0,0 +1,17 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 embedded brains GmbH & Co. KG + +.. index:: events + +.. _RTEMSAPIClassicEvent: + +Event Manager +************* + +.. toctree:: + + introduction + background + operations + directives diff --git a/c-user/event/introduction.rst b/c-user/event/introduction.rst new file mode 100644 index 0000000..ebdec2d --- /dev/null +++ b/c-user/event/introduction.rst @@ -0,0 +1,39 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. 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 +.. 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://www.rtems.org/bugs.html +.. +.. 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 + +.. Generated from spec:/rtems/event/if/group + +.. _EventManagerIntroduction: + +Introduction +============ + +.. The following list was generated from: +.. spec:/rtems/event/if/send +.. spec:/rtems/event/if/receive + +The Event Manager provides a high performance method of inter-task +communication and synchronization. The directives provided by the Event Manager +are: + +* :ref:`InterfaceRtemsEventSend` - Sends the event set to the task. + +* :ref:`InterfaceRtemsEventReceive` - Receives or gets an event set from the + calling task. diff --git a/c-user/event/operations.rst b/c-user/event/operations.rst new file mode 100644 index 0000000..e01b6dc --- /dev/null +++ b/c-user/event/operations.rst @@ -0,0 +1,63 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Operations +========== + +Sending an Event Set +-------------------- + +The ``rtems_event_send`` directive allows a task (or an ISR) to direct an event +set to a target task. Based upon the state of the target task, one of the +following situations applies: + +- Target Task is Blocked Waiting for Events + + - If the waiting task's input event condition is satisfied, then the task is + made ready for execution. + + - If the waiting task's input event condition is not satisfied, then the + event set is posted but left pending and the task remains blocked. + +- Target Task is Not Waiting for Events + + - The event set is posted and left pending. + +Receiving an Event Set +---------------------- + +The ``rtems_event_receive`` directive is used by tasks to accept a specific +input event condition. The task also specifies whether the request is +satisfied when all requested events are available or any single requested event +is available. If the requested event condition is satisfied by pending events, +then a successful return code and the satisfying event set are returned +immediately. If the condition is not satisfied, then one of the following +situations applies: + +- By default, the calling task will wait forever for the event condition to be + satisfied. + +- Specifying the ``RTEMS_NO_WAIT`` option forces an immediate return with an + error status code. + +- Specifying a timeout limits the period the task will wait before returning + with an error status code. + +Determining the Pending Event Set +--------------------------------- + +A task can determine the pending event set by calling the +``rtems_event_receive`` directive with a value of ``RTEMS_PENDING_EVENTS`` for +the input event condition. The pending events are returned to the calling task +but the event set is left unaltered. + +Receiving all Pending Events +---------------------------- + +A task can receive all of the currently pending events by calling the +``rtems_event_receive`` directive with a value of ``RTEMS_ALL_EVENTS`` for the +input event condition and ``RTEMS_NO_WAIT | RTEMS_EVENT_ANY`` for the option +set. The pending events are returned to the calling task and the event set is +cleared. If no events are pending then the ``RTEMS_UNSATISFIED`` status code +will be returned. |