spec: Update /rtems/message/* documentation

9 files changed, 354 insertions, 54 deletions

diff --git a/spec/rtems/message/constraint/receive-isr.yml b/spec/rtems/message/constraint/receive-isr.yml
new file mode 100644
index 00000000..45da94c6
--- /dev/null
+++ b/spec/rtems/message/constraint/receive-isr.yml
@@ -0,0 +1,11 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+links: []
+rationale: null
+scope: user
+text: |
+  When a local queue is accessed and the ${../../option/if/no-wait:/name}
+  option is set, the directive may be called from within interrupt context.
+type: constraint
diff --git a/spec/rtems/message/if/broadcast.yml b/spec/rtems/message/if/broadcast.yml
index 374195b3..8cb96b32 100644
--- a/spec/rtems/message/if/broadcast.yml
+++ b/spec/rtems/message/if/broadcast.yml
@@ -1,7 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Broadcasts the messages to the tasks waiting at the queue.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 definition:
   default:
@@ -14,31 +15,72 @@ definition:
     - ${/c/if/uint32_t:/name} *${.:/params[3]/name}
     return: ${../../status/if/code:/name}
   variants: []
-description: null
+description: |
+  This directive causes all tasks that are waiting at the queue specified by
+  ${.:/params[0]/name} to be unblocked and sent the message contained in
+  ${.:/params[1]/name}.  Before a task is unblocked, the message
+  ${.:/params[1]/name} of ${.:/params[2]/name} byes in length is copied to that
+  task's message buffer.  The number of tasks that were unblocked is returned
+  in ${.:/params[3]/name}.
 enabled-by: true
-index-entries: []
+index-entries:
+- broadcast message to a queue
 interface-type: function
 links:
 - role: interface-placement
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-task
+- role: constraint
+  uid: /constraint/directive-ctx-isr
+- role: constraint
+  uid: /constraint/unblock-may-preempt
+- role: constraint
+  uid: /constraint/directive-remote
 name: rtems_message_queue_broadcast
-notes: null
+notes: |
+  The execution time of this directive is directly related to the number of
+  tasks waiting on the message queue, although it is more efficient than the
+  equivalent number of invocations of ${send:/name}.
 params:
-- description: '%'
+- description: |
+    is the queue identifier.
   dir: null
   name: id
-- description: '%'
+- description: |
+    is the begin address of the message buffer to broadcast.
   dir: null
   name: buffer
-- description: '%'
+- description: |
+    is the size in bytes of the message buffer to broadcast.
   dir: null
   name: size
-- description: '%'
-  dir: null
+- description: |
+    is the pointer to an ${/c/if/uint32_t:/name} variable.  When the directive
+    call is successful, the number of unblocked tasks will be stored in this
+    variable.
+  dir: out
   name: count
 return:
   return: null
-  return-values: []
+  return-values:
+  - description: |
+      The requested operation was successful.
+    value: ${../../status/if/successful:/name}
+  - description: |
+      There was no queue associated with the identifier specified by
+      ${.:/params[0]/name}.
+    value: ${../../status/if/invalid-id:/name}
+  - description: |
+      The ${.:/params[1]/name} parameter was ${/c/if/null:/name}.
+    value: ${../../status/if/invalid-address:/name}
+  - description: |
+      The ${.:/params[3]/name} parameter was ${/c/if/null:/name}.
+    value: ${../../status/if/invalid-address:/name}
+  - description: |
+      The size of the message exceeded the maximum message size of the queue as
+      defined by ${create:/name} or ${construct:/name}.
+    value: ${../../status/if/invalid-size:/name}
 type: interface
diff --git a/spec/rtems/message/if/delete.yml b/spec/rtems/message/if/delete.yml
index fb170c97..6071ae39 100644
--- a/spec/rtems/message/if/delete.yml
+++ b/spec/rtems/message/if/delete.yml
@@ -72,6 +72,6 @@ return:
       ${.:/params[0]/name}.
     value: ${../../status/if/invalid-id:/name}
   - description: |
-      The semaphore resided on a remote node.
+      The message queue resided on a remote node.
     value: ${../../status/if/illegal-on-remote-object:/name}
 type: interface
diff --git a/spec/rtems/message/if/flush.yml b/spec/rtems/message/if/flush.yml
index 6e504aa3..27ee2ca7 100644
--- a/spec/rtems/message/if/flush.yml
+++ b/spec/rtems/message/if/flush.yml
@@ -1,7 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Flushes all messages on the queue.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 definition:
   default:
@@ -12,25 +13,50 @@ definition:
     - ${/c/if/uint32_t:/name} *${.:/params[1]/name}
     return: ${../../status/if/code:/name}
   variants: []
-description: null
+description: |
+  This directive removes all pending messages from the queue specified by
+  ${.:/params[0]/name}.  The number of messages removed is returned in
+  ${.:/params[1]/name}.  If no messages are present on the queue, count is set
+  to zero.
 enabled-by: true
-index-entries: []
+index-entries:
+- flush messages on a queue
 interface-type: function
 links:
 - role: interface-placement
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-task
+- role: constraint
+  uid: /constraint/directive-ctx-isr
+- role: constraint
+  uid: /constraint/directive-remote
 name: rtems_message_queue_flush
 notes: null
 params:
-- description: '%'
+- description: |
+    is the queue identifier.
   dir: null
   name: id
-- description: '%'
-  dir: null
+- description: |
+    is the pointer to an ${/c/if/uint32_t:/name} variable.  When the directive
+    call is successful, the number of unblocked tasks will be stored in this
+    variable.
+  dir: out
   name: count
 return:
   return: null
-  return-values: []
+  return-values:
+  - description: |
+      The requested operation was successful.
+    value: ${../../status/if/successful:/name}
+  - description: |
+      There was no queue associated with the identifier specified by
+      ${.:/params[0]/name}.
+    value: ${../../status/if/invalid-id:/name}
+  - description: |
+      The ${.:/params[1]/name} parameter was ${/c/if/null:/name}.
+    value: ${../../status/if/invalid-address:/name}
 type: interface
diff --git a/spec/rtems/message/if/get-number-pending.yml b/spec/rtems/message/if/get-number-pending.yml
index 508260e6..ed0fb250 100644
--- a/spec/rtems/message/if/get-number-pending.yml
+++ b/spec/rtems/message/if/get-number-pending.yml
@@ -1,7 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Gets the number of messages pending on the queue.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 definition:
   default:
@@ -12,25 +13,49 @@ definition:
     - ${/c/if/uint32_t:/name} *${.:/params[1]/name}
     return: ${../../status/if/code:/name}
   variants: []
-description: null
+description: |
+  This directive returns the number of messages pending on the queue specified
+  by ${.:/params[0]/name} in ${.:/params[1]/name}.  If no messages are present
+  on the queue, count is set to zero.
 enabled-by: true
-index-entries: []
+index-entries:
+- get number of pending messages
 interface-type: function
 links:
 - role: interface-placement
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-task
+- role: constraint
+  uid: /constraint/directive-ctx-isr
+- role: constraint
+  uid: /constraint/directive-remote
 name: rtems_message_queue_get_number_pending
 notes: null
 params:
-- description: '%'
+- description: |
+    is the queue identifier.
   dir: null
   name: id
-- description: '%'
-  dir: null
+- description: |
+    is the pointer to an ${/c/if/uint32_t:/name} variable.  When the directive
+    call is successful, the number of pending messages will be stored in this
+    variable.
+  dir: out
   name: count
 return:
   return: null
-  return-values: []
+  return-values:
+  - description: |
+      The requested operation was successful.
+    value: ${../../status/if/successful:/name}
+  - description: |
+      There was no queue associated with the identifier specified by
+      ${.:/params[0]/name}.
+    value: ${../../status/if/invalid-id:/name}
+  - description: |
+      The ${.:/params[1]/name} parameter was ${/c/if/null:/name}.
+    value: ${../../status/if/invalid-address:/name}
 type: interface
diff --git a/spec/rtems/message/if/group.yml b/spec/rtems/message/if/group.yml
index 26da474c..fe654c34 100644
--- a/spec/rtems/message/if/group.yml
+++ b/spec/rtems/message/if/group.yml
@@ -15,6 +15,28 @@ links:
   uid: header
 - role: interface-ingroup
   uid: ../../if/group
+- role: placement-order
+  uid: create
+- role: placement-order
+  uid: construct
+- role: placement-order
+  uid: ident
+- role: placement-order
+  uid: delete
+- role: placement-order
+  uid: send
+- role: placement-order
+  uid: urgent
+- role: placement-order
+  uid: broadcast
+- role: placement-order
+  uid: receive
+- role: placement-order
+  uid: get-number-pending
+- role: placement-order
+  uid: flush
+- role: placement-order
+  uid: buffer
 name: Message Manager
 text: |
   The Classic API shall provide an interface to the Message Manager.
diff --git a/spec/rtems/message/if/receive.yml b/spec/rtems/message/if/receive.yml
index 56f9a8ca..10a0d049 100644
--- a/spec/rtems/message/if/receive.yml
+++ b/spec/rtems/message/if/receive.yml
@@ -1,7 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Receives a message from the queue.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 definition:
   default:
@@ -15,34 +16,131 @@ definition:
     - ${../../type/if/interval:/name} ${.:/params[4]/name}
     return: ${../../status/if/code:/name}
   variants: []
-description: null
+description: |
+  This directive receives a message from the queue specified by
+  ${.:/params[0]/name}.
+
+  The **option set** specified in ${.:/params[3]/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 calling task can **wait** or **try to receive** a message from the queue
+  according to the mutually exclusive ${../../option/if/wait:/name} and
+  ${../../option/if/no-wait:/name} options.
+
+  * **Waiting to receive** a message from the queue is the default and can be
+    emphasized through the use of the ${../../option/if/wait:/name} option.
+    The ${.:/params[4]/name} 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.
+
+  * **Trying to receive** a message from the queue is selected by the
+    ${../../option/if/no-wait:/name} option.  If this option is defined, then
+    the ${.:/params[4]/name} parameter is ignored.  When a message from the
+    queue cannot be immediately received, then the
+    ${../../status/if/unsatisfied:/name} status is returned.
+
+  With either ${../../option/if/wait:/name} or ${../../option/if/no-wait:/name}
+  if there is at least one message in the queue, then it is copied to the
+  buffer, the size is set to return the length of the message in bytes, and
+  this directive returns immediately with the
+  ${../../status/if/successful:/name} status code.  The buffer has to be big
+  enough to receive a message of the maximum length with respect to this
+  message queue.
+
+  If the calling task chooses to return immediately and the queue is empty,
+  then the directive returns immediately with the
+  ${../../status/if/unsatisfied:/name} status cod.  If the calling task chooses
+  to wait at the message queue and the queue is empty, then the calling task is
+  placed on the message wait queue and blocked.  If the queue was created with
+  the ${../../attr/if/priority:/name} option specified, then the calling task
+  is inserted into the wait queue according to its priority.  But, if the queue
+  was created with the ${../../attr/if/fifo:/name} option specified, then the
+  calling task is placed at the rear of the wait queue.
 enabled-by: true
-index-entries: []
+index-entries:
+- receive message from a queue
 interface-type: function
 links:
 - role: interface-placement
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: ../constraint/receive-isr
+- role: constraint
+  uid: /constraint/directive-ctx-task
+- role: constraint
+  uid: ../../constraint/request-may-block
+- role: constraint
+  uid: /constraint/clock-tick
+- role: constraint
+  uid: /constraint/directive-remote
 name: rtems_message_queue_receive
 notes: null
 params:
-- description: '%'
+- description: |
+    is the queue identifier.
   dir: null
   name: id
-- description: '%'
+- description: |
+    is the begin address of the buffer to receive the message.  The buffer
+    shall be large enough to receive a message of the maximum length of the
+    queue as defined by ${create:/name} or ${construct:/name}.  The
+    ${.:/params[2]/name} parameter cannot be used to specify the size of the
+    buffer.
   dir: null
   name: buffer
-- description: '%'
+- description: |
+    is the pointer to a ${/c/if/size_t:/name} variable.  When the directive
+    call is successful, the size in bytes of the received messages will be
+    stored in this variable.  This parameter cannot be used to specify the size
+    of the buffer.
   dir: null
   name: size
-- description: '%'
+- description: |
+    is the option set.
   dir: null
   name: option_set
-- description: '%'
+- description: |
+    is the timeout in ${/glossary/clock-tick:/plural} if the
+    ${../../option/if/wait:/name} option is set.  Use
+    ${../../type/if/no-timeout:/name} to wait potentially forever.
   dir: null
   name: timeout
 return:
   return: null
-  return-values: []
+  return-values:
+  - description: |
+      The requested operation was successful.
+    value: ${../../status/if/successful:/name}
+  - description: |
+      There was no queue associated with the identifier specified by
+      ${.:/params[0]/name}.
+    value: ${../../status/if/invalid-id:/name}
+  - description: |
+      The ${.:/params[1]/name} parameter was ${/c/if/null:/name}.
+    value: ${../../status/if/invalid-address:/name}
+  - description: |
+      The ${.:/params[2]/name} parameter was ${/c/if/null:/name}.
+    value: ${../../status/if/invalid-address:/name}
+  - description: |
+      The queue was empty.
+    value: ${../../status/if/unsatisfied:/name}
+  - description: |
+      The queue was flushed while the calling task was waiting to receive a
+      message.
+    value: ${../../status/if/unsatisfied:/name}
+  - description: |
+      The timeout happened while the calling task was waiting to receive a
+      message
+    value: ${../../status/if/timeout:/name}
+  - description: |
+      The queue was deleted while the calling task was waiting to receive a
+      message.
+    value: ${../../status/if/object-was-deleted:/name}
 type: interface
diff --git a/spec/rtems/message/if/send.yml b/spec/rtems/message/if/send.yml
index e5aa74c2..91fb52e6 100644
--- a/spec/rtems/message/if/send.yml
+++ b/spec/rtems/message/if/send.yml
@@ -1,7 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Puts the message at the rear of the queue.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 definition:
   default:
@@ -13,28 +14,65 @@ definition:
     - ${/c/if/size_t:/name} ${.:/params[2]/name}
     return: ${../../status/if/code:/name}
   variants: []
-description: null
+description: |
+  This directive sends the message ${.:/params[1]/name} of ${.:/params[2]/name}
+  bytes in length to the queue specified by ${.:/params[0]/name}.  If a task is
+  waiting at the queue, then the message is copied to the waiting task's buffer
+  and the task is unblocked. If no tasks are waiting at the queue, then the
+  message is copied to a message buffer which is obtained from this message
+  queue's message buffer pool.  The message buffer is then placed at the rear
+  of the queue.
 enabled-by: true
-index-entries: []
+index-entries:
+- send message to a queue
 interface-type: function
 links:
 - role: interface-placement
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-task
+- role: constraint
+  uid: /constraint/directive-ctx-isr
+- role: constraint
+  uid: /constraint/unblock-may-preempt
+- role: constraint
+  uid: /constraint/directive-remote
 name: rtems_message_queue_send
 notes: null
 params:
-- description: '%'
+- description: |
+    is the queue identifier.
   dir: null
   name: id
-- description: '%'
+- description: |
+    is the begin address of the message buffer to send.
   dir: null
   name: buffer
-- description: '%'
+- description: |
+    is the size in bytes of the message buffer to send.
   dir: null
   name: size
 return:
   return: null
-  return-values: []
+  return-values:
+  - description: |
+      The requested operation was successful.
+    value: ${../../status/if/successful:/name}
+  - description: |
+      There was no queue associated with the identifier specified by
+      ${.:/params[0]/name}.
+    value: ${../../status/if/invalid-id:/name}
+  - description: |
+      The ${.:/params[1]/name} parameter was ${/c/if/null:/name}.
+    value: ${../../status/if/invalid-address:/name}
+  - description: |
+      The size of the message exceeded the maximum message size of the queue as
+      defined by ${create:/name} or ${construct:/name}.
+    value: ${../../status/if/invalid-size:/name}
+  - description: |
+      The maximum number of pending messages supported by the queue as defined
+      by ${create:/name} or ${construct:/name} has been reached.
+    value: ${../../status/if/too-many:/name}
 type: interface
diff --git a/spec/rtems/message/if/urgent.yml b/spec/rtems/message/if/urgent.yml
index 96588268..b42b4623 100644
--- a/spec/rtems/message/if/urgent.yml
+++ b/spec/rtems/message/if/urgent.yml
@@ -1,7 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Puts the message at the front of the queue.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 definition:
   default:
@@ -13,28 +14,65 @@ definition:
     - ${/c/if/size_t:/name} ${.:/params[2]/name}
     return: ${../../status/if/code:/name}
   variants: []
-description: null
+description: |
+  This directive sends the message ${.:/params[1]/name} of ${.:/params[2]/name}
+  bytes in length to the queue specified by ${.:/params[0]/name}.  If a task is
+  waiting at the queue, then the message is copied to the waiting task's buffer
+  and the task is unblocked. If no tasks are waiting at the queue, then the
+  message is copied to a message buffer which is obtained from this message
+  queue's message buffer pool.  The message buffer is then placed at the front
+  of the queue.
 enabled-by: true
-index-entries: []
+index-entries:
+- put message at front of queue
 interface-type: function
 links:
 - role: interface-placement
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-task
+- role: constraint
+  uid: /constraint/directive-ctx-isr
+- role: constraint
+  uid: /constraint/unblock-may-preempt
+- role: constraint
+  uid: /constraint/directive-remote
 name: rtems_message_queue_urgent
 notes: null
 params:
-- description: '%'
+- description: |
+    is the queue identifier.
   dir: null
   name: id
-- description: '%'
+- description: |
+    is the begin address of the message buffer to send urgently.
   dir: null
   name: buffer
-- description: '%'
+- description: |
+    is the size in bytes of the message buffer to send urgently.
   dir: null
   name: size
 return:
   return: null
-  return-values: []
+  return-values:
+  - description: |
+      The requested operation was successful.
+    value: ${../../status/if/successful:/name}
+  - description: |
+      There was no queue associated with the identifier specified by
+      ${.:/params[0]/name}.
+    value: ${../../status/if/invalid-id:/name}
+  - description: |
+      The ${.:/params[1]/name} parameter was ${/c/if/null:/name}.
+    value: ${../../status/if/invalid-address:/name}
+  - description: |
+      The size of the message exceeded the maximum message size of the queue as
+      defined by ${create:/name} or ${construct:/name}.
+    value: ${../../status/if/invalid-size:/name}
+  - description: |
+      The maximum number of pending messages supported by the queue as defined
+      by ${create:/name} or ${construct:/name} has been reached.
+    value: ${../../status/if/too-many:/name}
 type: interface