spec: Add event manager documentation

16 files changed, 177 insertions, 53 deletions

diff --git a/spec/if/rtems/event/all-events.yml b/spec/if/rtems/event/all-events.yml
index 0c657c37..235fa6fb 100644
--- a/spec/if/rtems/event/all-events.yml
+++ b/spec/if/rtems/event/all-events.yml
@@ -1,12 +1,15 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  This constant contains all events in an event set.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 definition:
   default: '0xffffffff'
   variants: []
-description: null
+description: |
+  The value of this constant is identical to ${event-0:/name} | ... |
+  ${event-31:/name}.
 enabled-by: true
 interface-type: define
 links:
diff --git a/spec/if/rtems/event/pending-events.yml b/spec/if/rtems/event/pending-events.yml
index 94c0c976..1183d173 100644
--- a/spec/if/rtems/event/pending-events.yml
+++ b/spec/if/rtems/event/pending-events.yml
@@ -1,5 +1,6 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  This constant used to get the set of pending events in ${receive:/name}.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
diff --git a/spec/if/rtems/event/receive.yml b/spec/if/rtems/event/receive.yml
index 5ce0ae06..31f7c2fb 100644
--- a/spec/if/rtems/event/receive.yml
+++ b/spec/if/rtems/event/receive.yml
@@ -1,5 +1,6 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Receives or gets an event set.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
@@ -13,7 +14,54 @@ definition:
     - ${set:/name} *${.:/params[3]/name}
     return: ${../status/code:/name}
   variants: []
-description: null
+description: |
+  This directive can be used to
+
+  * get the pending events of the task, or
+
+  * receive events.
+
+  To *get the pending event set* 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.
+
+  To *receive events* you have to define an input event condition and some
+  options.  The option set specified in ``${.:/params[2]/name}`` defines
+
+  * if the task will wait or poll for the events, and
+
+  * if the task wants to receive all or any of the input events.
+
+  The option set is built through a *bitwise or* of the option constants
+  described below.
+
+  The task can *wait* or *poll* for the events.
+
+  * Waiting for events is the default and can be emphasized through the use of
+    the ${../options/wait:/name} option.  The ``${.:/params[2]/name}``
+    parameter defines how long the task is willing to wait.  Use
+    ${../types/no-timeout:/name} to wait potentially forever, otherwise set a
+    timeout interval in clock ticks.
+
+  * Not waiting for events (polling) is selected by the
+    ${../options/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}``.
+
+  * Receiving all input events is the default and can be emphasized through the use
+    of the ${../options/event-all:/name} option.
+
+  * Receiving any of the input events is selected by the
+    ${../options/event-any:/name} option.
+
+  To receive all events use the constant ${all-events:/name} for the
+  ``${.:/params[0]/name}`` parameter.  This constant is identical to
+  ${event-0:/name} | ... | ${event-31:/name} and should not be confused with
+  the option ${../options/event-all:/name}.
 enabled-by: true
 interface-type: function
 links:
@@ -22,21 +70,53 @@ links:
 - role: interface-ingroup
   uid: /groups/api/classic/event
 name: rtems_event_receive
-notes: null
+notes: |
+  This directive shall be called by a task.  Calling this directive from
+  interrupt context is undefined behaviour.
+
+  This directive only affects the events specified in ``${.:/params[0]/name}``.
+  Any pending events that do not correspond to any of the events specified in
+  ``${.:/params[0]/name}`` will be left pending.
+
+  A task can *receive all of the pending events* by calling the directive with
+  a value of ${all-events:/name} for the ``${.:/params[0]/name}`` parameter and
+  ${../options/no-wait:/name} | ${../options/event-any:/name} for the
+  ``${.:/params[1]/name}`` parameter.  The pending events are returned to the
+  calling task and the event set of the task is cleared.  If no events are
+  pending then the ${../status/unsatisfied:/name} status code will be returned.
 params:
-- description: '%'
+- description: |
+    is the event set of interest.  Use ${pending-events:/name} to get the
+    pending events.
   dir: null
   name: event_in
-- description: '%'
+- description: is the option set.
   dir: null
   name: option_set
-- description: '%'
+- description: |
+    is the timeout in clock ticks if the ${../options/wait:/name} option was
+    set.  Use ${../types/no-timeout:/name} to wait potentially forever.
   dir: null
   name: ticks
-- description: '%'
+- description: |
+    is the pointer to an event set.  The received or pending events are stored
+    in the referenced event set if the operation was successful.
   dir: null
   name: event_out
 return:
   return: null
-  return-values: []
+  return-values:
+  - description: |
+      The requested operation was successful.
+    value: ${../status/successful:/name}
+  - description: |
+      The ``${.:/params[3]/name}`` parameter was ${/if/c/null:/name}.
+    value: ${../status/invalid-address:/name}
+  - description: |
+      The events of interest were not immediately available.
+    value: ${../status/unsatisfied:/name}
+  - description: |
+      The events of interest were not available within the specified timeout
+      interval.
+    value: ${../status/timeout:/name}
 type: interface
diff --git a/spec/if/rtems/event/send.yml b/spec/if/rtems/event/send.yml
index 4f107c2f..7d06ae49 100644
--- a/spec/if/rtems/event/send.yml
+++ b/spec/if/rtems/event/send.yml
@@ -1,5 +1,6 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Sends an event set to a task.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
@@ -11,7 +12,21 @@ definition:
     - ${set:/name} ${.:/params[1]/name}
     return: ${../status/code:/name}
   variants: []
-description: null
+description: |
+  This directive sends an event set, ``${.:/params[1]/name}``, to the task
+  specified by ``${.:/params[0]/name}``.  Based upon the state of the target
+  task, one of the following situations applies:
+
+  * The target task is blocked waiting for events, then
+
+    * if the waiting task's input event condition is satisfied, then the task
+      is made ready for execution, or
+
+    * otherwise, the event set is posted but left pending and the task remains
+      blocked.
+
+  * The target task is not waiting for events, then the event set is posted and
+    left pending.
 enabled-by: true
 interface-type: function
 links:
@@ -20,15 +35,40 @@ links:
 - role: interface-ingroup
   uid: /groups/api/classic/event
 name: rtems_event_send
-notes: null
+notes: |
+  Events can be sent by tasks or an ${/glossary/isr:/term}. 
+
+  Specifying ${../tasks/self-define:/name} for ``${.:/params[0]/name}`` results
+  in the event set being sent to the calling task.
+
+  The event set to send shall be built by a *bitwise or* of the desired events.
+  The set of valid events is ${event-0:/name} through ${event-31:/name}.  If an
+  event is not explicitly specified in the set, then it is not present.
+
+  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
+  ${receive:/name} 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.
 params:
-- description: '%'
+- description: is the identifier of the target task to receive the event set.
   dir: null
   name: id
-- description: '%'
+- description: is the event set to send.
   dir: null
   name: event_in
 return:
   return: null
-  return-values: []
+  return-values:
+  - description: |
+      The requested operation was successful.
+    value: ${../status/successful:/name}
+  - description: |
+      There was no task with the specified identifier.
+    value: ${../status/invalid-id:/name}
 type: interface
diff --git a/spec/if/rtems/event/set.yml b/spec/if/rtems/event/set.yml
index 09253afc..8ae92aa3 100644
--- a/spec/if/rtems/event/set.yml
+++ b/spec/if/rtems/event/set.yml
@@ -1,5 +1,7 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  This integer type can hold an event set of up to 32 events represented as a
+  bit field.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
diff --git a/spec/if/rtems/event/system-network-close.yml b/spec/if/rtems/event/system-network-close.yml
index f381733f..db5149de 100644
--- a/spec/if/rtems/event/system-network-close.yml
+++ b/spec/if/rtems/event/system-network-close.yml
@@ -1,5 +1,6 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  This is a reserved system event for a network socket close.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
@@ -12,8 +13,6 @@ interface-type: define
 links:
 - role: interface-placement
   uid: header
-- role: interface-ingroup
-  uid: /groups/api/classic/event
 name: RTEMS_EVENT_SYSTEM_NETWORK_CLOSE
 notes: null
 type: interface
diff --git a/spec/if/rtems/event/system-network-sbwait.yml b/spec/if/rtems/event/system-network-sbwait.yml
index 91a23113..d1fe0b83 100644
--- a/spec/if/rtems/event/system-network-sbwait.yml
+++ b/spec/if/rtems/event/system-network-sbwait.yml
@@ -1,5 +1,6 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  This is a reserved system event for a network socket buffer wait usage.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
@@ -12,8 +13,6 @@ interface-type: define
 links:
 - role: interface-placement
   uid: header
-- role: interface-ingroup
-  uid: /groups/api/classic/event
 name: RTEMS_EVENT_SYSTEM_NETWORK_SBWAIT
 notes: null
 type: interface
diff --git a/spec/if/rtems/event/system-network-sosleep.yml b/spec/if/rtems/event/system-network-sosleep.yml
index 5af63e39..483afb96 100644
--- a/spec/if/rtems/event/system-network-sosleep.yml
+++ b/spec/if/rtems/event/system-network-sosleep.yml
@@ -1,5 +1,6 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  This is a reserved system event for a network socket sleep usage.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
@@ -12,8 +13,6 @@ interface-type: define
 links:
 - role: interface-placement
   uid: header
-- role: interface-ingroup
-  uid: /groups/api/classic/event
 name: RTEMS_EVENT_SYSTEM_NETWORK_SOSLEEP
 notes: null
 type: interface
diff --git a/spec/if/rtems/event/system-receive.yml b/spec/if/rtems/event/system-receive.yml
index 8f17d5fe..f03a5d07 100644
--- a/spec/if/rtems/event/system-receive.yml
+++ b/spec/if/rtems/event/system-receive.yml
@@ -1,5 +1,6 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Receives or gets a system event set.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
@@ -13,27 +14,33 @@ definition:
     - ${set:/name} *${.:/params[3]/name}
     return: ${../status/code:/name}
   variants: []
-description: null
+description: |
+  This directive performs the same actions as the ${receive:/name} directive
+  except that it operates with a different set of events for each task.
 enabled-by: true
 interface-type: function
 links:
 - role: interface-placement
   uid: header
-- role: interface-ingroup
-  uid: /groups/api/classic/event
 name: rtems_event_system_receive
 notes: null
 params:
-- description: '%'
+- description: |
+    is the event set of interest.  Use ${pending-events:/name} to get the
+    pending events.
   dir: null
   name: event_in
-- description: '%'
+- description: is the option set.
   dir: null
   name: option_set
-- description: '%'
+- description: |
+    is the timeout in clock ticks if the ${../options/wait:/name} option was
+    set.  Use ${../types/no-timeout:/name} to wait potentially forever.
   dir: null
   name: ticks
-- description: '%'
+- description: |
+    is the pointer to an event set.  The received or pending events are stored
+    in the referenced event set if the operation was successful.
   dir: null
   name: event_out
 return:
diff --git a/spec/if/rtems/event/system-send.yml b/spec/if/rtems/event/system-send.yml
index f8b7d0ca..11b93b35 100644
--- a/spec/if/rtems/event/system-send.yml
+++ b/spec/if/rtems/event/system-send.yml
@@ -1,5 +1,6 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Sends a system event set to a task.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
@@ -17,15 +18,13 @@ interface-type: function
 links:
 - role: interface-placement
   uid: header
-- role: interface-ingroup
-  uid: /groups/api/classic/event
 name: rtems_event_system_send
 notes: null
 params:
-- description: '%'
+- description: is the identifier of the target task to receive the event set.
   dir: null
   name: id
-- description: '%'
+- description: is the event set to send.
   dir: null
   name: event_in
 return:
diff --git a/spec/if/rtems/event/system-server-resume.yml b/spec/if/rtems/event/system-server-resume.yml
index 59ee0651..2aec771c 100644
--- a/spec/if/rtems/event/system-server-resume.yml
+++ b/spec/if/rtems/event/system-server-resume.yml
@@ -1,5 +1,7 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  This is a reserved system event to resume a server thread, for example the
+  timer or interrupt server.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
@@ -12,8 +14,6 @@ interface-type: define
 links:
 - role: interface-placement
   uid: header
-- role: interface-ingroup
-  uid: /groups/api/classic/event
 name: RTEMS_EVENT_SYSTEM_SERVER_RESUME
 notes: null
 type: interface
diff --git a/spec/if/rtems/event/system-server.yml b/spec/if/rtems/event/system-server.yml
index dd6522a6..b4300340 100644
--- a/spec/if/rtems/event/system-server.yml
+++ b/spec/if/rtems/event/system-server.yml
@@ -1,5 +1,7 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  This is a reserved system event for server thread usage, for example the
+  timer or interrupt server.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
@@ -12,8 +14,6 @@ interface-type: define
 links:
 - role: interface-placement
   uid: header
-- role: interface-ingroup
-  uid: /groups/api/classic/event
 name: RTEMS_EVENT_SYSTEM_SERVER
 notes: null
 type: interface
diff --git a/spec/if/rtems/event/system-transient.yml b/spec/if/rtems/event/system-transient.yml
index 17763130..3098cf51 100644
--- a/spec/if/rtems/event/system-transient.yml
+++ b/spec/if/rtems/event/system-transient.yml
@@ -1,5 +1,6 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  This is a reserved system event for transient usage.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
diff --git a/spec/if/rtems/event/transient-clear.yml b/spec/if/rtems/event/transient-clear.yml
index db2369ae..363b5a2f 100644
--- a/spec/if/rtems/event/transient-clear.yml
+++ b/spec/if/rtems/event/transient-clear.yml
@@ -23,8 +23,6 @@ interface-type: function
 links:
 - role: interface-placement
   uid: header
-- role: interface-ingroup
-  uid: /groups/api/classic/clock
 name: rtems_event_transient_clear
 notes: null
 params: []
diff --git a/spec/if/rtems/event/transient-receive.yml b/spec/if/rtems/event/transient-receive.yml
index ff8c1ed2..5de7617e 100644
--- a/spec/if/rtems/event/transient-receive.yml
+++ b/spec/if/rtems/event/transient-receive.yml
@@ -25,8 +25,6 @@ interface-type: function
 links:
 - role: interface-placement
   uid: header
-- role: interface-ingroup
-  uid: /groups/api/classic/clock
 name: rtems_event_transient_receive
 notes: null
 params:
diff --git a/spec/if/rtems/event/transient-send.yml b/spec/if/rtems/event/transient-send.yml
index e5c43daa..38f6e254 100644
--- a/spec/if/rtems/event/transient-send.yml
+++ b/spec/if/rtems/event/transient-send.yml
@@ -17,8 +17,6 @@ interface-type: function
 links:
 - role: interface-placement
   uid: header
-- role: interface-ingroup
-  uid: /groups/api/classic/clock
 name: rtems_event_transient_send
 notes: null
 params: