mirror of
https://git.rtems.org/rtems-docs/
synced 2025-06-03 20:24:31 +08:00
ba6825ca63
This makes it easier to automatically generate parts of the manager documentation in the future. Update #3993.
97 lines
3.8 KiB
ReStructuredText
97 lines
3.8 KiB
ReStructuredText
.. 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``.
|