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