From fd6dc8c8de4dbc7ecf8a82a597cd5b43476fc8e3 Mon Sep 17 00:00:00 2001 From: Amar Takhar Date: Sun, 17 Jan 2016 19:19:43 -0500 Subject: Split document into seperate files by section. --- c_user/event_manager.rst | 298 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 298 insertions(+) create mode 100644 c_user/event_manager.rst (limited to 'c_user/event_manager.rst') diff --git a/c_user/event_manager.rst b/c_user/event_manager.rst new file mode 100644 index 0000000..cfe3cc5 --- /dev/null +++ b/c_user/event_manager.rst @@ -0,0 +1,298 @@ +Event Manager +############# + +.. index:: events + +Introduction +============ + +The event manager provides a high performance method +of intertask communication and synchronization. The directives +provided by the event manager are: + +- ``rtems_event_send`` - Send event set to a task + +- ``rtems_event_receive`` - Receive event condition + +Background +========== + +Event Sets +---------- +.. index:: event flag, definition +.. index:: event set, definition +.. index:: rtems_event_set + +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. + +Building an Event Set or Condition +---------------------------------- +.. index:: event condition, building +.. index:: event set, building + +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: + +- ``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``. + +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. + +Directives +========== + +This section details the event manager’s directives. +A subsection is dedicated to each of this manager’s directives +and describes the calling sequence, related constants, usage, +and status codes. + +EVENT_SEND - Send event set to a task +------------------------------------- +.. index:: send event set to a task + +**CALLING SEQUENCE:** + +.. index:: rtems_event_send + +.. code:: c + + rtems_status_code rtems_event_send ( + rtems_id id, + rtems_event_set event_in + ); + +**DIRECTIVE STATUS CODES:** + +``RTEMS_SUCCESSFUL`` - event set sent successfully +``RTEMS_INVALID_ID`` - invalid task id + +**DESCRIPTION:** + +This directive sends an event set, event_in, to the +task specified by id. If a blocked task’s input event condition +is satisfied by this directive, then it will be made ready. If +its input event condition is not satisfied, then the events +satisfied are updated and the events not satisfied are left +pending. If the task specified by id is not blocked waiting for +events, then the events sent are left pending. + +**NOTES:** + +Specifying ``RTEMS_SELF`` for id results in the event set being +sent to the calling task. + +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 ``rtems_event_receive`` +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. + +EVENT_RECEIVE - Receive event condition +--------------------------------------- +.. index:: receive event condition + +**CALLING SEQUENCE:** + +.. index:: rtems_event_receive + +.. code:: c + + rtems_status_code rtems_event_receive ( + rtems_event_set event_in, + rtems_option option_set, + rtems_interval ticks, + rtems_event_set \*event_out + ); + +**DIRECTIVE STATUS CODES:** + +``RTEMS_SUCCESSFUL`` - event received successfully +``RTEMS_UNSATISFIED`` - input event not satisfied (``RTEMS_NO_WAIT``) +``RTEMS_INVALID_ADDRESS`` - ``event_out`` is NULL +``RTEMS_TIMEOUT`` - timed out waiting for event + +**DESCRIPTION:** + +This directive attempts to receive the event +condition specified in event_in. If event_in is set to``RTEMS_PENDING_EVENTS``, then the current pending events are returned in +event_out and left pending. The ``RTEMS_WAIT`` and ``RTEMS_NO_WAIT`` options in the +option_set parameter are used to specify whether or not the task +is willing to wait for the event condition to be satisfied.``RTEMS_EVENT_ANY`` and ``RTEMS_EVENT_ALL`` are used in the option_set parameter are +used to specify whether a single event or the complete event set +is necessary to satisfy the event condition. The event_out +parameter is returned to the calling task with the value that +corresponds to the events in event_in that were satisfied. + +If pending events satisfy the event condition, then +event_out is set to the satisfied events and the pending events +in the event condition are cleared. If the event condition is +not satisfied and ``RTEMS_NO_WAIT`` is specified, then event_out is set to +the currently satisfied events. If the calling task chooses to +wait, then it will block waiting for the event condition. + +If the calling task must wait for the event condition +to be satisfied, then the timeout parameter is used to specify +the maximum interval to wait. If it is set to ``RTEMS_NO_TIMEOUT``, then +the calling task will wait forever. + +**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. + +The following event receive option constants are defined by +RTEMS: + +- ``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 + +A clock tick is required to support the functionality of this directive. + +.. COMMENT: COPYRIGHT (c) 1988-2002. + +.. COMMENT: On-Line Applications Research Corporation (OAR). + +.. COMMENT: All rights reserved. + -- cgit v1.2.3