spec: Document all create directives

1 files changed, 62 insertions, 10 deletions

diff --git a/spec/rtems/userext/if/create.yml b/spec/rtems/userext/if/create.yml
index 5b61f944..245fca32 100644
--- a/spec/rtems/userext/if/create.yml
+++ b/spec/rtems/userext/if/create.yml
@@ -1,7 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Creates an extension set.
 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,79 @@ definition:
     - ${../../type/if/id:/name} *${.:/params[2]/name}
     return: ${../../status/if/code:/name}
   variants: []
-description: null
+description: |
+  This directive creates an extension set which resides on the local node.  The
+  extension set has the user-defined object name specified in
+  ${.:/params[0]/name}.  The assigned object identifier is returned in
+  ${.:/params[2]/name}.  This identifier is used to access the extension set
+  with other extension set related directives.
+
+  The extension set is initialized using the extension table specified in
+  ${.:/params[1]/name}.
 enabled-by: true
-index-entries: []
+index-entries:
+- create an extension set
 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
 name: rtems_extension_create
-notes: null
+notes: |
+  The user-provided extension set table is not used after the return of the
+  directive.
+
+  Newly created extension sets are immediately installed and are invoked upon
+  the next system event supporting an extension.
+
+  An alternative to dynamically created extension sets are initial extensions,
+  see ${/acfg/if/initial-extensions:/name}.  Initial extensions are recommended
+  for extension sets which provide a fatal error extension.
+
+  For control and maintenance of the extension set, RTEMS allocates a
+  ${/glossary/escb:/term} from the local ESCB free pool and initializes it.
 params:
-- description: '%'
+- description: |
+    is the object name of the extension set.
   dir: null
   name: name
-- description: '%'
+- description: |
   dir: null
   name: extension_table
-- description: '%'
-  dir: null
+- description: |
+    is the pointer to an object identifier variable.  The identifier of the
+    created extension set 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[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: |
+      There was no inactive object available to create an extension set.  The
+      number of extension sets available to the application is configured
+      through the ${/acfg/if/max-user-extensions:/name} application
+      configuration option.
+    value: ${../../status/if/too-many:/name}
 type: interface