1 | .. comment SPDX-License-Identifier: CC-BY-SA-4.0 |
---|
2 | |
---|
3 | .. COMMENT: COPYRIGHT (c) 1988-2008. |
---|
4 | .. COMMENT: On-Line Applications Research Corporation (OAR). |
---|
5 | .. COMMENT: All rights reserved. |
---|
6 | |
---|
7 | Event Manager |
---|
8 | ############# |
---|
9 | |
---|
10 | .. index:: events |
---|
11 | |
---|
12 | Introduction |
---|
13 | ============ |
---|
14 | |
---|
15 | The event manager provides a high performance method of intertask communication |
---|
16 | and synchronization. The directives provided by the event manager are: |
---|
17 | |
---|
18 | - rtems_event_send_ - Send event set to a task |
---|
19 | - rtems_event_receive_ - Receive event condition |
---|
20 | |
---|
21 | Background |
---|
22 | ========== |
---|
23 | |
---|
24 | Event Sets |
---|
25 | ---------- |
---|
26 | .. index:: event flag, definition |
---|
27 | .. index:: event set, definition |
---|
28 | .. index:: rtems_event_set |
---|
29 | |
---|
30 | An event flag is used by a task (or ISR) to inform another task of the |
---|
31 | occurrence of a significant situation. Thirty-two event flags are associated |
---|
32 | with each task. A collection of one or more event flags is referred to as an |
---|
33 | event set. The data type ``rtems_event_set`` is used to manage event sets. |
---|
34 | |
---|
35 | The application developer should remember the following key characteristics of |
---|
36 | event operations when utilizing the event manager: |
---|
37 | |
---|
38 | - Events provide a simple synchronization facility. |
---|
39 | |
---|
40 | - Events are aimed at tasks. |
---|
41 | |
---|
42 | - Tasks can wait on more than one event simultaneously. |
---|
43 | |
---|
44 | - Events are independent of one another. |
---|
45 | |
---|
46 | - Events do not hold or transport data. |
---|
47 | |
---|
48 | - Events are not queued. In other words, if an event is sent more than once to |
---|
49 | a task before being received, the second and subsequent send operations to |
---|
50 | that same task have no effect. |
---|
51 | |
---|
52 | An event set is posted when it is directed (or sent) to a task. A pending |
---|
53 | event is an event that has been posted but not received. An event condition is |
---|
54 | used to specify the event set which the task desires to receive and the |
---|
55 | algorithm which will be used to determine when the request is satisfied. An |
---|
56 | event condition is satisfied based upon one of two algorithms which are |
---|
57 | selected by the user. The ``RTEMS_EVENT_ANY`` algorithm states that an event |
---|
58 | condition is satisfied when at least a single requested event is posted. The |
---|
59 | ``RTEMS_EVENT_ALL`` algorithm states that an event condition is satisfied when |
---|
60 | every requested event is posted. |
---|
61 | |
---|
62 | Building an Event Set or Condition |
---|
63 | ---------------------------------- |
---|
64 | .. index:: event condition, building |
---|
65 | .. index:: event set, building |
---|
66 | |
---|
67 | An event set or condition is built by a bitwise OR of the desired events. The |
---|
68 | set of valid events is ``RTEMS_EVENT_0`` through ``RTEMS_EVENT_31``. If an |
---|
69 | event is not explicitly specified in the set or condition, then it is not |
---|
70 | present. Events are specifically designed to be mutually exclusive, therefore |
---|
71 | bitwise OR and addition operations are equivalent as long as each event appears |
---|
72 | exactly once in the event set list. |
---|
73 | |
---|
74 | For example, when sending the event set consisting of ``RTEMS_EVENT_6``, |
---|
75 | ``RTEMS_EVENT_15``, and ``RTEMS_EVENT_31``, the event parameter to the |
---|
76 | ``rtems_event_send`` directive should be ``RTEMS_EVENT_6 | RTEMS_EVENT_15 | |
---|
77 | RTEMS_EVENT_31``. |
---|
78 | |
---|
79 | Building an EVENT_RECEIVE Option Set |
---|
80 | ------------------------------------ |
---|
81 | |
---|
82 | In general, an option is built by a bitwise OR of the desired option |
---|
83 | components. The set of valid options for the ``rtems_event_receive`` directive |
---|
84 | are listed in the following table: |
---|
85 | |
---|
86 | .. list-table:: |
---|
87 | :class: rtems-table |
---|
88 | |
---|
89 | * - ``RTEMS_WAIT`` |
---|
90 | - task will wait for event (default) |
---|
91 | * - ``RTEMS_NO_WAIT`` |
---|
92 | - task should not wait |
---|
93 | * - ``RTEMS_EVENT_ALL`` |
---|
94 | - return after all events (default) |
---|
95 | * - ``RTEMS_EVENT_ANY`` |
---|
96 | - return after any events |
---|
97 | |
---|
98 | Option values are specifically designed to be mutually exclusive, therefore |
---|
99 | bitwise OR and addition operations are equivalent as long as each option |
---|
100 | appears exactly once in the component list. An option listed as a default is |
---|
101 | not required to appear in the option list, although it is a good programming |
---|
102 | practice to specify default options. If all defaults are desired, the option |
---|
103 | ``RTEMS_DEFAULT_OPTIONS`` should be specified on this call. |
---|
104 | |
---|
105 | This example demonstrates the option parameter needed to poll for all events in |
---|
106 | a particular event condition to arrive. The option parameter passed to the |
---|
107 | ``rtems_event_receive`` directive should be either ``RTEMS_EVENT_ALL | |
---|
108 | RTEMS_NO_WAIT`` or ``RTEMS_NO_WAIT``. The option parameter can be set to |
---|
109 | ``RTEMS_NO_WAIT`` because ``RTEMS_EVENT_ALL`` is the default condition for |
---|
110 | ``rtems_event_receive``. |
---|
111 | |
---|
112 | Operations |
---|
113 | ========== |
---|
114 | |
---|
115 | Sending an Event Set |
---|
116 | -------------------- |
---|
117 | |
---|
118 | The ``rtems_event_send`` directive allows a task (or an ISR) to direct an event |
---|
119 | set to a target task. Based upon the state of the target task, one of the |
---|
120 | following situations applies: |
---|
121 | |
---|
122 | - Target Task is Blocked Waiting for Events |
---|
123 | |
---|
124 | - If the waiting task's input event condition is satisfied, then the task is |
---|
125 | made ready for execution. |
---|
126 | |
---|
127 | - If the waiting task's input event condition is not satisfied, then the |
---|
128 | event set is posted but left pending and the task remains blocked. |
---|
129 | |
---|
130 | - Target Task is Not Waiting for Events |
---|
131 | |
---|
132 | - The event set is posted and left pending. |
---|
133 | |
---|
134 | Receiving an Event Set |
---|
135 | ---------------------- |
---|
136 | |
---|
137 | The ``rtems_event_receive`` directive is used by tasks to accept a specific |
---|
138 | input event condition. The task also specifies whether the request is |
---|
139 | satisfied when all requested events are available or any single requested event |
---|
140 | is available. If the requested event condition is satisfied by pending events, |
---|
141 | then a successful return code and the satisfying event set are returned |
---|
142 | immediately. If the condition is not satisfied, then one of the following |
---|
143 | situations applies: |
---|
144 | |
---|
145 | - By default, the calling task will wait forever for the event condition to be |
---|
146 | satisfied. |
---|
147 | |
---|
148 | - Specifying the ``RTEMS_NO_WAIT`` option forces an immediate return with an |
---|
149 | error status code. |
---|
150 | |
---|
151 | - Specifying a timeout limits the period the task will wait before returning |
---|
152 | with an error status code. |
---|
153 | |
---|
154 | Determining the Pending Event Set |
---|
155 | --------------------------------- |
---|
156 | |
---|
157 | A task can determine the pending event set by calling the |
---|
158 | ``rtems_event_receive`` directive with a value of ``RTEMS_PENDING_EVENTS`` for |
---|
159 | the input event condition. The pending events are returned to the calling task |
---|
160 | but the event set is left unaltered. |
---|
161 | |
---|
162 | Receiving all Pending Events |
---|
163 | ---------------------------- |
---|
164 | |
---|
165 | A task can receive all of the currently pending events by calling the |
---|
166 | ``rtems_event_receive`` directive with a value of ``RTEMS_ALL_EVENTS`` for the |
---|
167 | input event condition and ``RTEMS_NO_WAIT | RTEMS_EVENT_ANY`` for the option |
---|
168 | set. The pending events are returned to the calling task and the event set is |
---|
169 | cleared. If no events are pending then the ``RTEMS_UNSATISFIED`` status code |
---|
170 | will be returned. |
---|
171 | |
---|
172 | Directives |
---|
173 | ========== |
---|
174 | |
---|
175 | This section details the event manager's directives. A subsection is dedicated |
---|
176 | to each of this manager's directives and describes the calling sequence, |
---|
177 | related constants, usage, and status codes. |
---|
178 | |
---|
179 | .. _rtems_event_send: |
---|
180 | |
---|
181 | EVENT_SEND - Send event set to a task |
---|
182 | ------------------------------------- |
---|
183 | .. index:: send event set to a task |
---|
184 | |
---|
185 | **CALLING SEQUENCE:** |
---|
186 | |
---|
187 | .. index:: rtems_event_send |
---|
188 | |
---|
189 | .. code-block:: c |
---|
190 | |
---|
191 | rtems_status_code rtems_event_send ( |
---|
192 | rtems_id id, |
---|
193 | rtems_event_set event_in |
---|
194 | ); |
---|
195 | |
---|
196 | **DIRECTIVE STATUS CODES:** |
---|
197 | |
---|
198 | .. list-table:: |
---|
199 | :class: rtems-table |
---|
200 | |
---|
201 | * - ``RTEMS_SUCCESSFUL`` |
---|
202 | - event set sent successfully |
---|
203 | * - ``RTEMS_INVALID_ID`` |
---|
204 | - invalid task id |
---|
205 | |
---|
206 | **DESCRIPTION:** |
---|
207 | |
---|
208 | This directive sends an event set, event_in, to the task specified by id. If a |
---|
209 | blocked task's input event condition is satisfied by this directive, then it |
---|
210 | will be made ready. If its input event condition is not satisfied, then the |
---|
211 | events satisfied are updated and the events not satisfied are left pending. If |
---|
212 | the task specified by id is not blocked waiting for events, then the events |
---|
213 | sent are left pending. |
---|
214 | |
---|
215 | **NOTES:** |
---|
216 | |
---|
217 | Specifying ``RTEMS_SELF`` for id results in the event set being sent to the |
---|
218 | calling task. |
---|
219 | |
---|
220 | Identical events sent to a task are not queued. In other words, the second, |
---|
221 | and subsequent, posting of an event to a task before it can perform an |
---|
222 | ``rtems_event_receive`` has no effect. |
---|
223 | |
---|
224 | The calling task will be preempted if it has preemption enabled and a higher |
---|
225 | priority task is unblocked as the result of this directive. |
---|
226 | |
---|
227 | Sending an event set to a global task which does not reside on the local node |
---|
228 | will generate a request telling the remote node to send the event set to the |
---|
229 | appropriate task. |
---|
230 | |
---|
231 | .. _rtems_event_receive: |
---|
232 | |
---|
233 | EVENT_RECEIVE - Receive event condition |
---|
234 | --------------------------------------- |
---|
235 | .. index:: receive event condition |
---|
236 | |
---|
237 | **CALLING SEQUENCE:** |
---|
238 | |
---|
239 | .. index:: rtems_event_receive |
---|
240 | |
---|
241 | .. code-block:: c |
---|
242 | |
---|
243 | rtems_status_code rtems_event_receive ( |
---|
244 | rtems_event_set event_in, |
---|
245 | rtems_option option_set, |
---|
246 | rtems_interval ticks, |
---|
247 | rtems_event_set *event_out |
---|
248 | ); |
---|
249 | |
---|
250 | **DIRECTIVE STATUS CODES:** |
---|
251 | |
---|
252 | .. list-table:: |
---|
253 | :class: rtems-table |
---|
254 | |
---|
255 | * - ``RTEMS_SUCCESSFUL`` |
---|
256 | - event received successfully |
---|
257 | * - ``RTEMS_UNSATISFIED`` |
---|
258 | - input event not satisfied (``RTEMS_NO_WAIT``) |
---|
259 | * - ``RTEMS_INVALID_ADDRESS`` |
---|
260 | - ``event_out`` is NULL |
---|
261 | * - ``RTEMS_TIMEOUT`` |
---|
262 | - timed out waiting for event |
---|
263 | |
---|
264 | **DESCRIPTION:** |
---|
265 | |
---|
266 | This directive attempts to receive the event condition specified in event_in. |
---|
267 | If event_in is set to ``RTEMS_PENDING_EVENTS``, then the current pending events |
---|
268 | are returned in event_out and left pending. The ``RTEMS_WAIT`` and |
---|
269 | ``RTEMS_NO_WAIT`` options in the option_set parameter are used to specify |
---|
270 | whether or not the task is willing to wait for the event condition to be |
---|
271 | satisfied. ``RTEMS_EVENT_ANY`` and ``RTEMS_EVENT_ALL`` are used in the |
---|
272 | option_set parameter are used to specify whether a single event or the complete |
---|
273 | event set is necessary to satisfy the event condition. The event_out parameter |
---|
274 | is returned to the calling task with the value that corresponds to the events |
---|
275 | in event_in that were satisfied. |
---|
276 | |
---|
277 | If pending events satisfy the event condition, then event_out is set to the |
---|
278 | satisfied events and the pending events in the event condition are cleared. If |
---|
279 | the event condition is not satisfied and ``RTEMS_NO_WAIT`` is specified, then |
---|
280 | event_out is set to the currently satisfied events. If the calling task |
---|
281 | chooses to wait, then it will block waiting for the event condition. |
---|
282 | |
---|
283 | If the calling task must wait for the event condition to be satisfied, then the |
---|
284 | timeout parameter is used to specify the maximum interval to wait. If it is |
---|
285 | set to ``RTEMS_NO_TIMEOUT``, then the calling task will wait forever. |
---|
286 | |
---|
287 | **NOTES:** |
---|
288 | |
---|
289 | This directive only affects the events specified in event_in. Any pending |
---|
290 | events that do not correspond to any of the events specified in event_in will |
---|
291 | be left pending. |
---|
292 | |
---|
293 | The following event receive option constants are defined by RTEMS: |
---|
294 | |
---|
295 | .. list-table:: |
---|
296 | :class: rtems-table |
---|
297 | |
---|
298 | * - ``RTEMS_WAIT`` |
---|
299 | - task will wait for event (default) |
---|
300 | * - ``RTEMS_NO_WAIT`` |
---|
301 | - task should not wait |
---|
302 | * - ``RTEMS_EVENT_ALL`` |
---|
303 | - return after all events (default) |
---|
304 | * - ``RTEMS_EVENT_ANY`` |
---|
305 | - return after any events |
---|
306 | |
---|
307 | A clock tick is required to support the functionality of this directive. |
---|