source: rtems/cpukit/include/rtems/rtems/event.h @ 2730599c

Last change on this file since 2730599c was 2730599c, checked in by Sebastian Huber <sebastian.huber@…>, on 01/27/21 at 05:10:15

rtems: Clarify event manager documentation

Unify the wording across similar directives of other managers. Add
"CONSTRAINTS" section.

Update #3993.

  • Property mode set to 100644
File size: 23.5 KB
Line 
1/* SPDX-License-Identifier: BSD-2-Clause */
2
3/**
4 * @file
5 *
6 * @ingroup RTEMSImplClassicEvent
7 *
8 * @brief This header file provides the Event Manager API.
9 */
10
11/*
12 * Copyright (C) 2014, 2021 embedded brains GmbH (http://www.embedded-brains.de)
13 * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
14 *
15 * Redistribution and use in source and binary forms, with or without
16 * modification, are permitted provided that the following conditions
17 * are met:
18 * 1. Redistributions of source code must retain the above copyright
19 *    notice, this list of conditions and the following disclaimer.
20 * 2. Redistributions in binary form must reproduce the above copyright
21 *    notice, this list of conditions and the following disclaimer in the
22 *    documentation and/or other materials provided with the distribution.
23 *
24 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
25 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
27 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
28 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
29 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
30 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
31 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
32 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
33 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
34 * POSSIBILITY OF SUCH DAMAGE.
35 */
36
37/*
38 * This file is part of the RTEMS quality process and was automatically
39 * generated.  If you find something that needs to be fixed or
40 * worded better please post a report or patch to an RTEMS mailing list
41 * or raise a bug report:
42 *
43 * https://www.rtems.org/bugs.html
44 *
45 * For information on updating and regenerating please refer to the How-To
46 * section in the Software Requirements Engineering chapter of the
47 * RTEMS Software Engineering manual.  The manual is provided as a part of
48 * a release.  For development sources please refer to the online
49 * documentation at:
50 *
51 * https://docs.rtems.org
52 */
53
54/* Generated from spec:/rtems/event/if/header */
55
56#ifndef _RTEMS_RTEMS_EVENT_H
57#define _RTEMS_RTEMS_EVENT_H
58
59#include <stdint.h>
60#include <rtems/rtems/options.h>
61#include <rtems/rtems/status.h>
62#include <rtems/rtems/types.h>
63
64#ifdef __cplusplus
65extern "C" {
66#endif
67
68/* Generated from spec:/rtems/event/if/group */
69
70/**
71 * @defgroup RTEMSAPIClassicEvent Event Manager
72 *
73 * @ingroup RTEMSAPIClassic
74 *
75 * @brief The Event Manager provides a high performance method of inter-task
76 *   communication and synchronization.
77 */
78
79/* Generated from spec:/rtems/event/if/all-events */
80
81/**
82 * @ingroup RTEMSAPIClassicEvent
83 *
84 * @brief This event set constant represents all events of an event set.
85 *
86 * This event set constant is equal to the bitwise or of #RTEMS_EVENT_0,
87 * #RTEMS_EVENT_1, #RTEMS_EVENT_2, #RTEMS_EVENT_3, #RTEMS_EVENT_4,
88 * #RTEMS_EVENT_5, #RTEMS_EVENT_6, #RTEMS_EVENT_7, #RTEMS_EVENT_8,
89 * #RTEMS_EVENT_9, #RTEMS_EVENT_10, #RTEMS_EVENT_11, #RTEMS_EVENT_12,
90 * #RTEMS_EVENT_13, #RTEMS_EVENT_14, #RTEMS_EVENT_15, #RTEMS_EVENT_16,
91 * #RTEMS_EVENT_17, #RTEMS_EVENT_18, #RTEMS_EVENT_19, #RTEMS_EVENT_20,
92 * #RTEMS_EVENT_21, #RTEMS_EVENT_22, #RTEMS_EVENT_23, #RTEMS_EVENT_24,
93 * #RTEMS_EVENT_25, #RTEMS_EVENT_26, #RTEMS_EVENT_27, #RTEMS_EVENT_28,
94 * #RTEMS_EVENT_29, #RTEMS_EVENT_30, and #RTEMS_EVENT_31.
95 */
96#define RTEMS_ALL_EVENTS 0xffffffff
97
98/* Generated from spec:/rtems/event/if/event-00 */
99
100/**
101 * @ingroup RTEMSAPIClassicEvent
102 *
103 * @brief This event set constant represents the bit in the event set
104 *   associated with event 0.
105 */
106#define RTEMS_EVENT_0 0x00000001
107
108/* Generated from spec:/rtems/event/if/event-01 */
109
110/**
111 * @ingroup RTEMSAPIClassicEvent
112 *
113 * @brief This event set constant represents the bit in the event set
114 *   associated with event 1.
115 */
116#define RTEMS_EVENT_1 0x00000002
117
118/* Generated from spec:/rtems/event/if/event-02 */
119
120/**
121 * @ingroup RTEMSAPIClassicEvent
122 *
123 * @brief This event set constant represents the bit in the event set
124 *   associated with event 2.
125 */
126#define RTEMS_EVENT_2 0x00000004
127
128/* Generated from spec:/rtems/event/if/event-03 */
129
130/**
131 * @ingroup RTEMSAPIClassicEvent
132 *
133 * @brief This event set constant represents the bit in the event set
134 *   associated with event 3.
135 */
136#define RTEMS_EVENT_3 0x00000008
137
138/* Generated from spec:/rtems/event/if/event-04 */
139
140/**
141 * @ingroup RTEMSAPIClassicEvent
142 *
143 * @brief This event set constant represents the bit in the event set
144 *   associated with event 4.
145 */
146#define RTEMS_EVENT_4 0x00000010
147
148/* Generated from spec:/rtems/event/if/event-05 */
149
150/**
151 * @ingroup RTEMSAPIClassicEvent
152 *
153 * @brief This event set constant represents the bit in the event set
154 *   associated with event 5.
155 */
156#define RTEMS_EVENT_5 0x00000020
157
158/* Generated from spec:/rtems/event/if/event-06 */
159
160/**
161 * @ingroup RTEMSAPIClassicEvent
162 *
163 * @brief This event set constant represents the bit in the event set
164 *   associated with event 6.
165 */
166#define RTEMS_EVENT_6 0x00000040
167
168/* Generated from spec:/rtems/event/if/event-07 */
169
170/**
171 * @ingroup RTEMSAPIClassicEvent
172 *
173 * @brief This event set constant represents the bit in the event set
174 *   associated with event 7.
175 */
176#define RTEMS_EVENT_7 0x00000080
177
178/* Generated from spec:/rtems/event/if/event-08 */
179
180/**
181 * @ingroup RTEMSAPIClassicEvent
182 *
183 * @brief This event set constant represents the bit in the event set
184 *   associated with event 8.
185 */
186#define RTEMS_EVENT_8 0x00000100
187
188/* Generated from spec:/rtems/event/if/event-09 */
189
190/**
191 * @ingroup RTEMSAPIClassicEvent
192 *
193 * @brief This event set constant represents the bit in the event set
194 *   associated with event 9.
195 */
196#define RTEMS_EVENT_9 0x00000200
197
198/* Generated from spec:/rtems/event/if/event-10 */
199
200/**
201 * @ingroup RTEMSAPIClassicEvent
202 *
203 * @brief This event set constant represents the bit in the event set
204 *   associated with event 10.
205 */
206#define RTEMS_EVENT_10 0x00000400
207
208/* Generated from spec:/rtems/event/if/event-11 */
209
210/**
211 * @ingroup RTEMSAPIClassicEvent
212 *
213 * @brief This event set constant represents the bit in the event set
214 *   associated with event 11.
215 */
216#define RTEMS_EVENT_11 0x00000800
217
218/* Generated from spec:/rtems/event/if/event-12 */
219
220/**
221 * @ingroup RTEMSAPIClassicEvent
222 *
223 * @brief This event set constant represents the bit in the event set
224 *   associated with event 12.
225 */
226#define RTEMS_EVENT_12 0x00001000
227
228/* Generated from spec:/rtems/event/if/event-13 */
229
230/**
231 * @ingroup RTEMSAPIClassicEvent
232 *
233 * @brief This event set constant represents the bit in the event set
234 *   associated with event 13.
235 */
236#define RTEMS_EVENT_13 0x00002000
237
238/* Generated from spec:/rtems/event/if/event-14 */
239
240/**
241 * @ingroup RTEMSAPIClassicEvent
242 *
243 * @brief This event set constant represents the bit in the event set
244 *   associated with event 14.
245 */
246#define RTEMS_EVENT_14 0x00004000
247
248/* Generated from spec:/rtems/event/if/event-15 */
249
250/**
251 * @ingroup RTEMSAPIClassicEvent
252 *
253 * @brief This event set constant represents the bit in the event set
254 *   associated with event 15.
255 */
256#define RTEMS_EVENT_15 0x00008000
257
258/* Generated from spec:/rtems/event/if/event-16 */
259
260/**
261 * @ingroup RTEMSAPIClassicEvent
262 *
263 * @brief This event set constant represents the bit in the event set
264 *   associated with event 16.
265 */
266#define RTEMS_EVENT_16 0x00010000
267
268/* Generated from spec:/rtems/event/if/event-17 */
269
270/**
271 * @ingroup RTEMSAPIClassicEvent
272 *
273 * @brief This event set constant represents the bit in the event set
274 *   associated with event 17.
275 */
276#define RTEMS_EVENT_17 0x00020000
277
278/* Generated from spec:/rtems/event/if/event-18 */
279
280/**
281 * @ingroup RTEMSAPIClassicEvent
282 *
283 * @brief This event set constant represents the bit in the event set
284 *   associated with event 18.
285 */
286#define RTEMS_EVENT_18 0x00040000
287
288/* Generated from spec:/rtems/event/if/event-19 */
289
290/**
291 * @ingroup RTEMSAPIClassicEvent
292 *
293 * @brief This event set constant represents the bit in the event set
294 *   associated with event 19.
295 */
296#define RTEMS_EVENT_19 0x00080000
297
298/* Generated from spec:/rtems/event/if/event-20 */
299
300/**
301 * @ingroup RTEMSAPIClassicEvent
302 *
303 * @brief This event set constant represents the bit in the event set
304 *   associated with event 20.
305 */
306#define RTEMS_EVENT_20 0x00100000
307
308/* Generated from spec:/rtems/event/if/event-21 */
309
310/**
311 * @ingroup RTEMSAPIClassicEvent
312 *
313 * @brief This event set constant represents the bit in the event set
314 *   associated with event 21.
315 */
316#define RTEMS_EVENT_21 0x00200000
317
318/* Generated from spec:/rtems/event/if/event-22 */
319
320/**
321 * @ingroup RTEMSAPIClassicEvent
322 *
323 * @brief This event set constant represents the bit in the event set
324 *   associated with event 22.
325 */
326#define RTEMS_EVENT_22 0x00400000
327
328/* Generated from spec:/rtems/event/if/event-23 */
329
330/**
331 * @ingroup RTEMSAPIClassicEvent
332 *
333 * @brief This event set constant represents the bit in the event set
334 *   associated with event 23.
335 */
336#define RTEMS_EVENT_23 0x00800000
337
338/* Generated from spec:/rtems/event/if/event-24 */
339
340/**
341 * @ingroup RTEMSAPIClassicEvent
342 *
343 * @brief This event set constant represents the bit in the event set
344 *   associated with event 24.
345 */
346#define RTEMS_EVENT_24 0x01000000
347
348/* Generated from spec:/rtems/event/if/event-25 */
349
350/**
351 * @ingroup RTEMSAPIClassicEvent
352 *
353 * @brief This event set constant represents the bit in the event set
354 *   associated with event 25.
355 */
356#define RTEMS_EVENT_25 0x02000000
357
358/* Generated from spec:/rtems/event/if/event-26 */
359
360/**
361 * @ingroup RTEMSAPIClassicEvent
362 *
363 * @brief This event set constant represents the bit in the event set
364 *   associated with event 26.
365 */
366#define RTEMS_EVENT_26 0x04000000
367
368/* Generated from spec:/rtems/event/if/event-27 */
369
370/**
371 * @ingroup RTEMSAPIClassicEvent
372 *
373 * @brief This event set constant represents the bit in the event set
374 *   associated with event 27.
375 */
376#define RTEMS_EVENT_27 0x08000000
377
378/* Generated from spec:/rtems/event/if/event-28 */
379
380/**
381 * @ingroup RTEMSAPIClassicEvent
382 *
383 * @brief This event set constant represents the bit in the event set
384 *   associated with event 28.
385 */
386#define RTEMS_EVENT_28 0x10000000
387
388/* Generated from spec:/rtems/event/if/event-29 */
389
390/**
391 * @ingroup RTEMSAPIClassicEvent
392 *
393 * @brief This event set constant represents the bit in the event set
394 *   associated with event 29.
395 */
396#define RTEMS_EVENT_29 0x20000000
397
398/* Generated from spec:/rtems/event/if/event-30 */
399
400/**
401 * @ingroup RTEMSAPIClassicEvent
402 *
403 * @brief This event set constant represents the bit in the event set
404 *   associated with event 30.
405 */
406#define RTEMS_EVENT_30 0x40000000
407
408/* Generated from spec:/rtems/event/if/event-31 */
409
410/**
411 * @ingroup RTEMSAPIClassicEvent
412 *
413 * @brief This event set constant represents the bit in the event set
414 *   associated with event 31.
415 */
416#define RTEMS_EVENT_31 0x80000000
417
418/* Generated from spec:/rtems/event/if/pending-events */
419
420/**
421 * @ingroup RTEMSAPIClassicEvent
422 *
423 * @brief This event set constant indicates that rtems_event_receive() shall
424 *   return the set of pending events.
425 */
426#define RTEMS_PENDING_EVENTS 0
427
428/* Generated from spec:/rtems/event/if/set */
429
430/**
431 * @ingroup RTEMSAPIClassicEvent
432 *
433 * @brief This integer type represents a bit field which can hold exactly 32
434 *   individual events.
435 */
436typedef uint32_t rtems_event_set;
437
438/* Generated from spec:/rtems/event/if/system-network-close */
439
440/**
441 * @brief This event set constant represents the reserved system event for a
442 *   network socket close.
443 */
444#define RTEMS_EVENT_SYSTEM_NETWORK_CLOSE RTEMS_EVENT_26
445
446/* Generated from spec:/rtems/event/if/system-network-sbwait */
447
448/**
449 * @brief This event set constant represents the reserved system event for a
450 *   network socket buffer wait usage.
451 */
452#define RTEMS_EVENT_SYSTEM_NETWORK_SBWAIT RTEMS_EVENT_24
453
454/* Generated from spec:/rtems/event/if/system-network-sosleep */
455
456/**
457 * @brief This event set constant represents the reserved system event for a
458 *   network socket sleep.
459 */
460#define RTEMS_EVENT_SYSTEM_NETWORK_SOSLEEP RTEMS_EVENT_25
461
462/* Generated from spec:/rtems/event/if/system-receive */
463
464/**
465 * @brief Receives or gets a system event set from the executing task.
466 *
467 * @param event_in is the event set of interest.  Use #RTEMS_PENDING_EVENTS to
468 *   get the pending events.
469 *
470 * @param option_set is the option set.
471 *
472 * @param ticks is the timeout in clock ticks if the #RTEMS_WAIT option was
473 *   set.  Use #RTEMS_NO_TIMEOUT to wait potentially forever.
474 *
475 * @param event_out is the pointer to an event set.  The received or pending
476 *   events are stored in the referenced event set if the operation was
477 *   successful.
478 *
479 * This directive performs the same actions as the rtems_event_receive()
480 * directive except that it operates with a different set of events for each
481 * task.
482 *
483 * @par Constraints
484 * @parblock
485 * The following constraints apply to this directive:
486 *
487 * * The directive may be called from within device driver initialization
488 *   context.
489 *
490 * * The directive may be called from within task context.
491 *
492 * * The timeout functionality of the directive requires a clock tick.
493 * @endparblock
494 */
495rtems_status_code rtems_event_system_receive(
496  rtems_event_set  event_in,
497  rtems_option     option_set,
498  rtems_interval   ticks,
499  rtems_event_set *event_out
500);
501
502/* Generated from spec:/rtems/event/if/system-send */
503
504/**
505 * @brief Sends the system event set to the task.
506 *
507 * @param id is the identifier of the target task to receive the event set.
508 *
509 * @param event_in is the event set to send.
510 *
511 * @par Constraints
512 * @parblock
513 * The following constraints apply to this directive:
514 *
515 * * The directive may be called from within interrupt context.
516 *
517 * * The directive may be called from within device driver initialization
518 *   context.
519 *
520 * * The directive may be called from within task context.
521 *
522 * * The directive may unblock another task which may preempt the calling task.
523 * @endparblock
524 */
525rtems_status_code rtems_event_system_send(
526  rtems_id        id,
527  rtems_event_set event_in
528);
529
530/* Generated from spec:/rtems/event/if/system-server */
531
532/**
533 * @brief This event set constant represents the reserved system event for
534 *   server thread usage, for example the timer or interrupt server.
535 */
536#define RTEMS_EVENT_SYSTEM_SERVER RTEMS_EVENT_30
537
538/* Generated from spec:/rtems/event/if/system-server-resume */
539
540/**
541 * @brief This event set constant represents the reserved system event to
542 *   resume a server thread, for example the timer or interrupt server.
543 */
544#define RTEMS_EVENT_SYSTEM_SERVER_RESUME RTEMS_EVENT_29
545
546/* Generated from spec:/rtems/event/if/system-transient */
547
548/**
549 * @brief This event set constant represents the reserved system event for
550 *   transient usage.
551 */
552#define RTEMS_EVENT_SYSTEM_TRANSIENT RTEMS_EVENT_31
553
554/* Generated from spec:/rtems/event/if/transient-clear */
555
556/**
557 * @brief Clears the transient event.
558 *
559 * @par Constraints
560 * @parblock
561 * The following constraints apply to this directive:
562 *
563 * * The directive may be called from within device driver initialization
564 *   context.
565 *
566 * * The directive may be called from within task context.
567 *
568 * * The directive will not cause the calling task to be preempted.
569 * @endparblock
570 */
571static inline void rtems_event_transient_clear( void )
572{
573  rtems_event_set event_out;
574
575  (void) rtems_event_system_receive(
576    RTEMS_EVENT_SYSTEM_TRANSIENT,
577    RTEMS_EVENT_ALL | RTEMS_NO_WAIT,
578    0,
579    &event_out
580  );
581}
582
583/* Generated from spec:/rtems/event/if/transient-receive */
584
585/**
586 * @brief Receives the transient event.
587 *
588 * @param option_set is the option set.
589 *
590 * @param ticks is the optional timeout in clock ticks.
591 *
592 * @par Constraints
593 * @parblock
594 * The following constraints apply to this directive:
595 *
596 * * The directive may be called from within device driver initialization
597 *   context.
598 *
599 * * The directive may be called from within task context.
600 *
601 * * The timeout functionality of the directive requires a clock tick.
602 * @endparblock
603 */
604static inline rtems_status_code rtems_event_transient_receive(
605  rtems_option   option_set,
606  rtems_interval ticks
607)
608{
609  rtems_event_set event_out;
610
611  return rtems_event_system_receive(
612    RTEMS_EVENT_SYSTEM_TRANSIENT,
613    RTEMS_EVENT_ALL | option_set,
614    ticks,
615    &event_out
616  );
617}
618
619/* Generated from spec:/rtems/event/if/transient-send */
620
621/**
622 * @brief Sends the transient event to the task.
623 *
624 * @param id is the identifier of the task to receive the transient event.
625 *
626 * @par Constraints
627 * @parblock
628 * The following constraints apply to this directive:
629 *
630 * * The directive may be called from within interrupt context.
631 *
632 * * The directive may be called from within device driver initialization
633 *   context.
634 *
635 * * The directive may be called from within task context.
636 *
637 * * The directive may unblock another task which may preempt the calling task.
638 * @endparblock
639 */
640static inline rtems_status_code rtems_event_transient_send( rtems_id id )
641{
642  return rtems_event_system_send( id, RTEMS_EVENT_SYSTEM_TRANSIENT );
643}
644
645/* Generated from spec:/rtems/event/if/send */
646
647/**
648 * @ingroup RTEMSAPIClassicEvent
649 *
650 * @brief Sends the event set to the task.
651 *
652 * @param id is the identifier of the target task to receive the event set.
653 *
654 * @param event_in is the event set to send.
655 *
656 * This directive sends the event set, ``event_in``, to the target task
657 * identified by ``id``.  Based upon the state of the target task, one of the
658 * following situations applies:
659 *
660 * * The target task is blocked waiting for events, then
661 *
662 *   * if the waiting task's input event condition is satisfied, then the task
663 *     is made ready for execution, or
664 *
665 *   * otherwise, the event set is posted but left pending and the task remains
666 *     blocked.
667 *
668 * * The target task is not waiting for events, then the event set is posted
669 *   and left pending.
670 *
671 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
672 *
673 * @retval ::RTEMS_INVALID_ID There was no task associated with the identifier
674 *   specified by ``id``.
675 *
676 * @par Notes
677 * @parblock
678 * Events can be sent by tasks or an ISR.
679 *
680 * Specifying #RTEMS_SELF for ``id`` results in the event set being sent to the
681 * calling task.
682 *
683 * The event set to send shall be built by a *bitwise or* of the desired
684 * events. The set of valid events is #RTEMS_EVENT_0 through #RTEMS_EVENT_31.
685 * If an event is not explicitly specified in the set, then it is not present.
686 *
687 * Identical events sent to a task are not queued.  In other words, the second,
688 * and subsequent, posting of an event to a task before it can perform an
689 * rtems_event_receive() has no effect.
690 *
691 * The calling task will be preempted if it has preemption enabled and a higher
692 * priority task is unblocked as the result of this directive.
693 *
694 * Sending an event set to a global task which does not reside on the local
695 * node will generate a request telling the remote node to send the event set
696 * to the appropriate task.
697 * @endparblock
698 *
699 * @par Constraints
700 * @parblock
701 * The following constraints apply to this directive:
702 *
703 * * The directive may be called from within interrupt context.
704 *
705 * * The directive may be called from within device driver initialization
706 *   context.
707 *
708 * * The directive may be called from within task context.
709 *
710 * * The directive may unblock another task which may preempt the calling task.
711 * @endparblock
712 */
713rtems_status_code rtems_event_send( rtems_id id, rtems_event_set event_in );
714
715/* Generated from spec:/rtems/event/if/receive */
716
717/**
718 * @ingroup RTEMSAPIClassicEvent
719 *
720 * @brief Receives or gets an event set from the calling task.
721 *
722 * @param event_in is the event set of interest.  Use #RTEMS_PENDING_EVENTS to
723 *   get the pending events.
724 *
725 * @param option_set is the option set.
726 *
727 * @param ticks is the timeout in clock ticks if the #RTEMS_WAIT option is set.
728 *   Use #RTEMS_NO_TIMEOUT to wait potentially forever.
729 *
730 * @param event_out is the pointer to an event set.  The received or pending
731 *   events are stored in the referenced event set if the operation was
732 *   successful.
733 *
734 * This directive can be used to
735 *
736 * * get the pending events of the calling task, or
737 *
738 * * receive events.
739 *
740 * To **get the pending events** use the constant #RTEMS_PENDING_EVENTS for the
741 * ``event_in`` parameter.  The pending events are returned to the calling task
742 * but the event set of the calling task is left unaltered.  The ``option_set``
743 * and ``ticks`` parameters are ignored in this case.  The directive returns
744 * immediately and does not block.
745 *
746 * To **receive events** you have to define an input event condition and some
747 * options.
748 *
749 * The **option set** specified in ``option_set`` is built through a *bitwise
750 * or* of the option constants described below.  Not all combinations of
751 * options are allowed.  Some options are mutually exclusive.  If mutually
752 * exclusive options are combined, the behaviour is undefined.  Options not
753 * mentioned below are not evaluated by this directive and have no effect.
754 * Default options can be selected by using the #RTEMS_DEFAULT_OPTIONS
755 * constant.  The option set defines
756 *
757 * * if the calling task will wait or poll for the events, and
758 *
759 * * if the calling task wants to receive all or any of the input events.
760 *
761 * The calling task can **wait** or **poll** for the events.
762 *
763 * * **Waiting** for events is the default and can be emphasized through the
764 *   use of the #RTEMS_WAIT option.  The ``ticks`` parameter defines how long
765 *   the calling task is willing to wait.  Use #RTEMS_NO_TIMEOUT to wait
766 *   potentially forever, otherwise set a timeout interval in clock ticks.
767 *
768 * * Not waiting for events (**polling**) is selected by the #RTEMS_NO_WAIT
769 *   option.  If this option is defined, then the ``ticks`` parameter is
770 *   ignored.
771 *
772 * The calling task can receive **all** or **any** of the input events
773 * specified in ``event_in``.
774 *
775 * * Receiving **all** input events is the default and can be emphasized
776 *   through the use of the #RTEMS_EVENT_ALL option.
777 *
778 * * Receiving **any** of the input events is selected by the #RTEMS_EVENT_ANY
779 *   option.
780 *
781 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
782 *
783 * @retval ::RTEMS_INVALID_ADDRESS The ``event_out`` parameter was NULL.
784 *
785 * @retval ::RTEMS_UNSATISFIED The events of interest were not immediately
786 *   available.
787 *
788 * @retval ::RTEMS_TIMEOUT The events of interest were not available within the
789 *   specified timeout interval.
790 *
791 * @par Notes
792 * @parblock
793 * This directive only affects the events specified in ``event_in``. Any
794 * pending events that do not correspond to any of the events specified in
795 * ``event_in`` will be left pending.
796 *
797 * To receive all events use the event set constant #RTEMS_ALL_EVENTS for the
798 * ``event_in`` parameter.  Do not confuse this event set constant with the
799 * directive option #RTEMS_EVENT_ALL.
800 *
801 * A task can **receive all of the pending events** by calling the directive
802 * with a value of #RTEMS_ALL_EVENTS for the ``event_in`` parameter and the
803 * bitwise or of the #RTEMS_NO_WAIT and #RTEMS_EVENT_ANY options for the
804 * ``option_set`` parameter.  The pending events are returned and the event set
805 * of the task is cleared.  If no events are pending then the
806 * ::RTEMS_UNSATISFIED status code will be returned.
807 * @endparblock
808 *
809 * @par Constraints
810 * @parblock
811 * The following constraints apply to this directive:
812 *
813 * * The directive may be called from within device driver initialization
814 *   context.
815 *
816 * * The directive may be called from within task context.
817 *
818 * * The timeout functionality of the directive requires a clock tick.
819 * @endparblock
820 */
821rtems_status_code rtems_event_receive(
822  rtems_event_set  event_in,
823  rtems_option     option_set,
824  rtems_interval   ticks,
825  rtems_event_set *event_out
826);
827
828#ifdef __cplusplus
829}
830#endif
831
832#endif /* _RTEMS_RTEMS_EVENT_H */
Note: See TracBrowser for help on using the repository browser.