spec: Document all create directives

1 files changed, 126 insertions, 12 deletions

diff --git a/spec/rtems/message/if/create.yml b/spec/rtems/message/if/create.yml
index c6822587..57d804e9 100644
--- a/spec/rtems/message/if/create.yml
+++ b/spec/rtems/message/if/create.yml
@@ -1,7 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Creates a message 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,147 @@ definition:
     - ${../../type/if/id:/name} *${.:/params[4]/name}
     return: ${../../status/if/code:/name}
   variants: []
-description: null
+description: |
+  This directive creates a message queue which resides on the local node.  The
+  message queue has the user-defined object name specified in
+  ${.:/params[0]/name}.  Memory is allocated from the RTEMS Workspace for the
+  count of messages specified in ${.:/params[1]/name}, each of
+  ${.:/params[2]/name} bytes in length.  The assigned object identifier is
+  returned in ${.:/params[4]/name}.  This identifier is used to access the
+  message queue with other message queue related directives.
+
+  The **attribute set** specified in ${.:/params[3]/name} is built through a
+  *bitwise or* of the attribute constants described below.  Not all
+  combinations of attributes are allowed.  Some attributes are mutually
+  exclusive.  If mutually exclusive attributes are combined, the behaviour is
+  undefined.  Attributes not mentioned below are not evaluated by this
+  directive and have no effect.  Default attributes can be selected by using
+  the ${../../attr/if/default:/name} constant.  The attribute set defines
+
+  * the scope of the message queue: ${../../attr/if/local:/name} (default) or
+    ${../../attr/if/global:/name} and
+
+  * the task wait queue discipline used by the message queue:
+    ${../../attr/if/fifo:/name} (default) or ${../../attr/if/priority:/name}.
+
+  The message queue has a local or global **scope** in a multiprocessing network
+  (this attribute does not refer to SMP systems).  The scope is selected by the
+  mutually exclusive ${../../attr/if/local:/name} and
+  ${../../attr/if/global:/name} attributes.
+
+  * A **local scope** is the default and can be emphasized through the use of
+    the ${../../attr/if/local:/name} attribute.  A local message queue can be
+    only used by the node which created it.
+
+  * A **global scope** is established if the ${../../attr/if/global:/name}
+    attribute is set.  Setting the global attribute in a single node system has
+    no effect.
+
+  The **task wait queue discipline** is selected by the mutually exclusive
+  ${../../attr/if/fifo:/name} and ${../../attr/if/priority:/name} attributes.
+  The discipline defines the order in which tasks wait for a message to receive
+  on a currently empty message queue.
+
+  * The **FIFO discipline** is the default and can be emphasized
+    through use of the ${../../attr/if/fifo:/name} attribute.
+
+  * The **priority discipline** is selected by the
+    ${../../attr/if/priority:/name} attribute.
 enabled-by: true
-index-entries: []
+index-entries:
+- create a message queue
 interface-type: function
 links:
 - role: interface-placement
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-devinit
+- role: constraint
+  uid: /constraint/directive-ctx-task
+- role: constraint
+  uid: /constraint/object-allocator
+- role: constraint
+  uid: ../constraint/max
+- role: constraint
+  uid: /constraint/obj-unlimited-alloc
+- role: constraint
+  uid: ../../constraint/mp-max-global-objects
 name: rtems_message_queue_create
-notes: null
+notes: |
+  For message queues with a global scope, the maximum message size is
+  effectively limited to the longest message which the ${/glossary/mpci:/term}
+  is capable of transmitting.
+
+  For control and maintenance of the message queue, RTEMS allocates a
+  ${/glossary/qcb:/term} from the local QCB free pool and initializes it.
+
+  The QCB for a global message queue is allocated on the local node.  Message
+  queues should not be made global unless remote tasks must interact with the
+  message queue.  This is to avoid the system overhead incurred by the creation
+  of a global message queue.  When a global message queue is created, the
+  message queue's name and identifier must be transmitted to every node in the
+  system for insertion in the local copy of the global object table.
 params:
-- description: '%'
+- description: |
+    is the object name of the message queue.
   dir: null
   name: name
-- description: '%'
+- description: |
+    is the maximum count of pending messages supported by the message queue.
   dir: null
   name: count
-- description: '%'
+- description: |
+    is the maximum size in bytes of a message supported by the message queue.
   dir: null
   name: max_message_size
-- description: '%'
+- description: |
+    is the attribute set of the message queue.
   dir: null
   name: attribute_set
-- description: '%'
-  dir: null
+- description: |
+    is the pointer to an object identifier variable.  The identifier of the
+    created message queue will be stored in this variable, in case of a
+    successful operation.
+  dir: out
   name: id
 return:
   return: null
-  return-values: []
+  return-values:
+  - description: |
+      The requested operation was successful.
+    value: ${../../status/if/successful:/name}
+  - description: |
+      The ${.:/params[0]/name} parameter was invalid.
+    value: ${../../status/if/invalid-name:/name}
+  - description: |
+      The ${.:/params[4]/name} parameter was ${/c/if/null:/name}.
+    value: ${../../status/if/invalid-address:/name}
+  - description: |
+      The ${.:/params[1]/name} parameter was invalid.
+    value: ${../../status/if/invalid-number:/name}
+  - description: |
+      The ${.:/params[2]/name} parameter was invalid.
+    value: ${../../status/if/invalid-size:/name}
+  - description: |
+      There was no inactive object available to create a message queue.  The
+      number of message queue available to the application is configured
+      through the ${/acfg/if/max-message-queues:/name} application
+      configuration option.
+    value: ${../../status/if/too-many:/name}
+  - description: |
+      In multiprocessing configurations, there was no inactive global object
+      available to create a global message queue.  The number of global objects
+      available to the application is configured through the
+      ${/acfg/if/mp-max-global-objects:/name} application configuration option.
+    value: ${../../status/if/too-many:/name}
+  - description: |
+      The product of ${.:/params[1]/name} and ${.:/params[2]/name} is greater
+      than the maximum storage size.
+    value: ${../../status/if/invalid-number:/name}
+  - description: |
+      There was not enough memory available in the RTEMS Workspace to allocate
+      the message buffers for the message queue.
+    value: ${../../status/if/unsatisfied:/name}
 type: interface