spec: Update /rtems/support/* documentation

11 files changed, 142 insertions, 56 deletions

diff --git a/spec/rtems/support/if/is-name-valid.yml b/spec/rtems/support/if/is-name-valid.yml
index aff5750f..cbf9435e 100644
--- a/spec/rtems/support/if/is-name-valid.yml
+++ b/spec/rtems/support/if/is-name-valid.yml
@@ -1,8 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
 brief: |
-  Returns true, if the specified object name is valid, otherwise returns false.
+  Checks if the object name is valid.
 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) 1989, 2008 On-Line Applications Research Corporation (OAR)
 definition:
   default:
@@ -22,17 +22,19 @@ links:
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-any
+- role: constraint
+  uid: /constraint/directive-no-preempt
 name: rtems_is_name_valid
 notes: null
 params:
-- description: is the object name to check.
+- description: |
+    is the object name to check.
   dir: null
   name: name
 return:
-  return: null
-  return-values:
-  - description: The specified object name is valid.
-    value: 'true'
-  - description: Otherwise.
-    value: 'false'
+  return: |
+    Returns true, if the object name is valid, otherwise false.
+  return-values: []
 type: interface
diff --git a/spec/rtems/support/if/microseconds-to-ticks.yml b/spec/rtems/support/if/microseconds-to-ticks.yml
index 6aa65914..57d7591f 100644
--- a/spec/rtems/support/if/microseconds-to-ticks.yml
+++ b/spec/rtems/support/if/microseconds-to-ticks.yml
@@ -1,8 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
 brief: |
-  Returns the number of clock ticks for the specified microseconds value.
+  Gets the number of clock ticks for the microseconds value.
 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) 2008 On-Line Applications Research Corporation (OAR)
 definition:
   default: |
@@ -17,16 +17,21 @@ links:
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-any
+- role: constraint
+  uid: /constraint/directive-no-preempt
 name: RTEMS_MICROSECONDS_TO_TICKS
 notes: |
   The number of clock ticks per second is defined by the
   ${/acfg/if/microseconds-per-tick:/name} application configuration option.
 params:
-- description: is the microseconds value to convert to clock ticks.
+- description: |
+    is the microseconds value to convert to clock ticks.
   dir: null
   name: _us
 return:
   return: |
-    The number of clock ticks for the specified microseconds value is returned.
+    Returns the number of clock ticks for the specified microseconds value.
   return-values: []
 type: interface
diff --git a/spec/rtems/support/if/milliseconds-to-microseconds.yml b/spec/rtems/support/if/milliseconds-to-microseconds.yml
index d80362b8..19cd055a 100644
--- a/spec/rtems/support/if/milliseconds-to-microseconds.yml
+++ b/spec/rtems/support/if/milliseconds-to-microseconds.yml
@@ -1,8 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
 brief: |
-  Returns the number of microseconds for the specified milliseconds value.
+  Gets the number of microseconds for the milliseconds value.
 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) 2008 On-Line Applications Research Corporation (OAR)
 definition:
   default: |
@@ -17,14 +17,19 @@ links:
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-const
+- role: constraint
+  uid: /constraint/directive-no-preempt
 name: RTEMS_MILLISECONDS_TO_MICROSECONDS
 notes: null
 params:
-- description: is the milliseconds value to convert to microseconds.
+- description: |
+    is the milliseconds value to convert to microseconds.
   dir: null
   name: _ms
 return:
   return: |
-    The number of microseconds for the specified milliseconds value is returned.
+    Returns the number of microseconds for the milliseconds value.
   return-values: []
 type: interface
diff --git a/spec/rtems/support/if/milliseconds-to-ticks.yml b/spec/rtems/support/if/milliseconds-to-ticks.yml
index c2524f19..d62e097a 100644
--- a/spec/rtems/support/if/milliseconds-to-ticks.yml
+++ b/spec/rtems/support/if/milliseconds-to-ticks.yml
@@ -1,8 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
 brief: |
-  Returns the number of clock ticks for the specified milliseconds value.
+  Gets the number of clock ticks for the milliseconds value.
 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) 2008 On-Line Applications Research Corporation (OAR)
 definition:
   default: |
@@ -17,16 +17,21 @@ links:
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-any
+- role: constraint
+  uid: /constraint/directive-no-preempt
 name: RTEMS_MILLISECONDS_TO_TICKS
 notes: |
   The number of clock ticks per second is defined by the
   ${/acfg/if/microseconds-per-tick:/name} application configuration option.
 params:
-- description: is the milliseconds value to convert to clock ticks.
+- description: |
+    is the milliseconds value to convert to clock ticks.
   dir: null
   name: _ms
 return:
   return: |
-    The number of clock ticks for the specified milliseconds value is returned.
+    Returns the number of clock ticks for the milliseconds value.
   return-values: []
 type: interface
diff --git a/spec/rtems/support/if/name-to-characters.yml b/spec/rtems/support/if/name-to-characters.yml
index b492d99d..99c01dc4 100644
--- a/spec/rtems/support/if/name-to-characters.yml
+++ b/spec/rtems/support/if/name-to-characters.yml
@@ -8,10 +8,10 @@ definition:
   default:
     attributes: null
     body: |
-      *${.:/params[1]/name} = (char) ( ${.:/params[0]/name} >> 24 );
-      *${.:/params[2]/name} = (char) ( ${.:/params[0]/name} >> 16 );
-      *${.:/params[3]/name} = (char) ( ${.:/params[0]/name} >> 8 );
-      *${.:/params[4]/name} = (char) ${.:/params[0]/name};
+      *${.:/params[1]/name} = (char) ( ( ( ${.:/params[0]/name} ) >> 24 ) & 0xff );
+      *${.:/params[2]/name} = (char) ( ( ( ${.:/params[0]/name} ) >> 16 ) & 0xff );
+      *${.:/params[3]/name} = (char) ( ( ( ${.:/params[0]/name} ) >> 8 ) & 0xff );
+      *${.:/params[4]/name} = (char) ( ( ${.:/params[0]/name} ) & 0xff );
     params:
     - ${../../type/if/name:/name} ${.:/params[0]/name}
     - char *${.:/params[1]/name}
@@ -29,6 +29,10 @@ links:
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-any
+- role: constraint
+  uid: /constraint/directive-no-preempt
 name: rtems_name_to_characters
 notes: null
 params:
diff --git a/spec/rtems/support/if/workspace-allocate.yml b/spec/rtems/support/if/workspace-allocate.yml
index 8d0499cd..feb84b40 100644
--- a/spec/rtems/support/if/workspace-allocate.yml
+++ b/spec/rtems/support/if/workspace-allocate.yml
@@ -1,7 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Allocates a memory area from the RTEMS Workspace.
 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:
@@ -21,16 +22,28 @@ links:
   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
 name: rtems_workspace_allocate
-notes: null
+notes: |
+  This directive is intended to be used by tests of the RTEMS test suites.
 params:
-- description: '%'
+- description: |
+    is the number of bytes to allocated.
   dir: null
   name: bytes
-- description: '%'
-  dir: null
+- description: |
+    is the pointer to a pointer variable.  When the directive call is
+    successful, the begin address of the allocated memory area will be stored
+    in this variable.
+  dir: out
   name: pointer
 return:
-  return: null
+  return: |
+    Returns true, if the allocation was successful, otherwise false.
   return-values: []
 type: interface
diff --git a/spec/rtems/support/if/workspace-free.yml b/spec/rtems/support/if/workspace-free.yml
index 8f9a2f19..e10d5b30 100644
--- a/spec/rtems/support/if/workspace-free.yml
+++ b/spec/rtems/support/if/workspace-free.yml
@@ -1,7 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Frees the memory area allocated from the RTEMS Workspace.
 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:
@@ -20,13 +21,21 @@ links:
   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
 name: rtems_workspace_free
 notes: null
 params:
-- description: '%'
+- description: |
+    is the begin address of the memory area to free.
   dir: null
   name: pointer
 return:
-  return: null
+  return: |
+    Returns true, if freeing the memory area was successful, otherwise false.
   return-values: []
 type: interface
diff --git a/spec/rtems/support/if/workspace-get-information.yml b/spec/rtems/support/if/workspace-get-information.yml
index 4aa2d301..16253854 100644
--- a/spec/rtems/support/if/workspace-get-information.yml
+++ b/spec/rtems/support/if/workspace-get-information.yml
@@ -1,7 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Gets information about the RTEMS Workspace.
 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:
@@ -20,13 +21,22 @@ links:
   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
 name: rtems_workspace_get_information
 notes: null
 params:
-- description: '%'
+- description: |
+    is the pointer to a heap information variable.  When the directive call is
+    successful, the heap information will be stored in this variable.
   dir: null
   name: the_info
 return:
-  return: null
+  return: |
+    Returns true, if getting the information was successful, otherwise false.
   return-values: []
 type: interface
diff --git a/spec/rtems/support/if/workspace-greedy-allocate-all-except-largest.yml b/spec/rtems/support/if/workspace-greedy-allocate-all-except-largest.yml
index 1aa782e4..afbae878 100644
--- a/spec/rtems/support/if/workspace-greedy-allocate-all-except-largest.yml
+++ b/spec/rtems/support/if/workspace-greedy-allocate-all-except-largest.yml
@@ -1,7 +1,9 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Greedy allocates all blocks of the RTEMS Workspace except the largest free
+  block.
 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:
@@ -11,7 +13,10 @@ definition:
     - ${/c/if/uintptr_t:/name} *${.:/params[0]/name}
     return: void *
   variants: []
-description: null
+description: |
+  Afterwards the heap has at most one allocatable block.  This block is the
+  largest free block if it exists.  The allocatable size of this block is
+  stored in ${.:/params[0]/name}.  All other blocks are used.
 enabled-by: true
 index-entries: []
 interface-type: function
@@ -20,13 +25,23 @@ links:
   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
 name: rtems_workspace_greedy_allocate_all_except_largest
-notes: null
+notes: |
+  This directive is intended to be used by tests of the RTEMS test suites.
 params:
-- description: '%'
+- description: |
+    is the remaining allocatable size.
   dir: null
   name: allocatable_size
 return:
-  return: null
+  return: |
+    The returned pointer value may be used to free the greedy allocation by
+    calling ${workspace-greedy-free:/name}.
   return-values: []
 type: interface
diff --git a/spec/rtems/support/if/workspace-greedy-allocate.yml b/spec/rtems/support/if/workspace-greedy-allocate.yml
index 78860e83..eda9f512 100644
--- a/spec/rtems/support/if/workspace-greedy-allocate.yml
+++ b/spec/rtems/support/if/workspace-greedy-allocate.yml
@@ -1,7 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Greedy allocates that empties the RTEMS Workspace.
 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,7 +13,10 @@ definition:
     - ${/c/if/size_t:/name} ${.:/params[1]/name}
     return: void *
   variants: []
-description: null
+description: |
+  Afterwards the heap has at most ${.:/params[1]/name} allocatable blocks of
+  sizes specified by ${.:/params[0]/name}.  The ${.:/params[0]/name} must point
+  to an array with ${.:/params[1]/name} members.  All other blocks are used.
 enabled-by: true
 index-entries: []
 interface-type: function
@@ -24,13 +28,17 @@ links:
 name: rtems_workspace_greedy_allocate
 notes: null
 params:
-- description: '%'
+- description: |
+    is the array of block sizes.
   dir: null
   name: block_sizes
-- description: '%'
+- description: |
+    is the block count.
   dir: null
   name: block_count
 return:
-  return: null
+  return: |
+    The returned pointer value may be used to free the greedy allocation by
+    calling ${workspace-greedy-free:/name}.
   return-values: []
 type: interface
diff --git a/spec/rtems/support/if/workspace-greedy-free.yml b/spec/rtems/support/if/workspace-greedy-free.yml
index a54a4b0c..0a6b5920 100644
--- a/spec/rtems/support/if/workspace-greedy-free.yml
+++ b/spec/rtems/support/if/workspace-greedy-free.yml
@@ -1,7 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Frees space of a greedy allocation to the RTEMS Workspace.
 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:
@@ -20,10 +21,19 @@ links:
   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
 name: rtems_workspace_greedy_free
-notes: null
+notes: |
+  This directive is intended to be used by tests of the RTEMS test suites.
 params:
-- description: '%'
+- description: |
+    is the pointer value returned by ${workspace-greedy-allocate:/name} or
+    ${workspace-greedy-allocate-all-except-largest:/name}.
   dir: null
   name: opaque
 return: