spec: Update /rtems/message/* documentation

1 files changed, 53 insertions, 11 deletions

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