[rtems-central commit] spec: Clarify rtems_event_receive()

[Sebastian Huber]

Module:    rtems-central
Branch:    master
Commit:    58b444f2fd596d3258c88ff598a5835613e2623a
Changeset: http://git.rtems.org/rtems-central/commit/?id=58b444f2fd596d3258c88ff598a5835613e2623a

Author:    Sebastian Huber <sebastian.huber at embedded-brains.de>
Date:      Wed Jan 20 09:25:41 2021 +0100

spec: Clarify rtems_event_receive()

---

 spec/rtems/event/if/receive.yml | 33 +++++++++++++++++++--------------
 1 file changed, 19 insertions(+), 14 deletions(-)

diff --git a/spec/rtems/event/if/receive.yml b/spec/rtems/event/if/receive.yml
index 8e50297..9f3018c 100644
--- a/spec/rtems/event/if/receive.yml
+++ b/spec/rtems/event/if/receive.yml
@@ -2,7 +2,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
 brief: |
   Receives or gets an event set from the calling task.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 definition:
   default:
@@ -23,26 +23,31 @@ description: |
   * receive events.
 
   To **get the pending events** use the constant ${pending-events:/name} for
-  the ${.:/params[0]/name} parameter.  The pending events are returned to
-  the calling task but the event set of the task is left unaltered.  The
-  ${.:/params[1]/name} and ${.:/params[2]/name} parameters are ignored
-  in this case.  The directive returns immediately and does not block.
+  the ${.:/params[0]/name} parameter.  The pending events are returned to the
+  calling task but the event set of the calling task is left unaltered.  The
+  ${.:/params[1]/name} and ${.:/params[2]/name} parameters are ignored in this
+  case.  The directive returns immediately and does not block.
 
   To **receive events** you have to define an input event condition and some
-  options.  The **option set** specified in ${.:/params[1]/name} defines
+  options.
 
-  * if the task will wait or poll for the events, and
+  The **option set** specified in ${.:/params[1]/name} is built through a
+  *bitwise or* of the option constants described below.  Not all combinations
+  of options are allowed.  Some options are mutually exclusive.  If mutually
+  exclusive options are combined, the behaviour is undefined.  Options not
+  mentioned below are not evaluated by this directive and have no effect.
+  Default options can be selected by using the ${../../option/if/default:/name}
+  constant.  The option set defines
 
-  * if the task wants to receive all or any of the input events.
+  * if the calling task will wait or poll for the events, and
 
-  The option set is built through a *bitwise or* of the option constants
-  described below.
+  * if the calling task wants to receive all or any of the input events.
 
-  The task can **wait** or **poll** for the events.
+  The calling task can **wait** or **poll** for the events.
 
   * **Waiting** for events is the default and can be emphasized through the use
     of the ${../../option/if/wait:/name} option.  The ${.:/params[2]/name}
-    parameter defines how long the task is willing to wait.  Use
+    parameter defines how long the calling task is willing to wait.  Use
     ${../../type/if/no-timeout:/name} to wait potentially forever, otherwise
     set a timeout interval in clock ticks.
 
@@ -50,8 +55,8 @@ description: |
     ${../../option/if/no-wait:/name} option.  If this option is defined, then
     the ${.:/params[2]/name} parameter is ignored.
 
-  The task can receive **all** or **any** of the input events specified in
-  ${.:/params[0]/name}.
+  The calling task can receive **all** or **any** of the input events specified
+  in ${.:/params[0]/name}.
 
   * Receiving **all** input events is the default and can be emphasized through
     the use of the ${../../option/if/event-all:/name} option.