spec: Update /rtems/region/* documentation

1 files changed, 45 insertions, 9 deletions

diff --git a/spec/rtems/region/if/get-free-information.yml b/spec/rtems/region/if/get-free-information.yml
index 0f817376..92f562fa 100644
--- a/spec/rtems/region/if/get-free-information.yml
+++ b/spec/rtems/region/if/get-free-information.yml
@@ -1,7 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Gets the region free information.
 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,60 @@ definition:
     - ${/score/heap/if/information-block:/name} *${.:/params[1]/name}
     return: ${../../status/if/code:/name}
   variants: []
-description: null
+description: |
+  This directive is used to obtain information about the free memory in the
+  region specified by ${.:/params[0/name}. This is a snapshot at the time of
+  the call. The information will be returned in the structure pointed to by
+  ${.:/params[1]/name}.
 enabled-by: true
-index-entries: []
+index-entries:
+- obtain region information on free blocks
 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
 name: rtems_region_get_free_information
-notes: null
+notes: |
+  This directive uses the same structure to return information as the
+  ${get-information:/name} directive but does not fill in the used information.
+
+  This is primarily intended as a mechanism to obtain a diagnostic information.
+  This method forms am O(n) scan of the free in the region to calculate the
+  information provided. Given that the execution time is driven by the number
+  of used and free blocks, it can take a non-deterministic time to execute.
+  Typically, there are many used blocks and a much smaller number of used
+  blocks making a call to this directive less expensive than a call to
+  ${get-information:/name}.
 params:
-- description: '%'
+- description: |
+    is the region identifier.
   dir: null
   name: id
-- description: '%'
-  dir: null
+- description: |
+    is the pointer to a ${/score/heap/if/information-block:/name} variable.
+    When the directive call is successful, the free information of the region
+    will be stored in this variable.
+  dir: out
   name: the_info
 return:
   return: null
-  return-values: []
+  return-values:
+  - description: |
+      The requested operation was successful.
+    value: ${../../status/if/successful:/name}
+  - description: |
+      The ${.:/params[1]/name} parameter was ${/c/if/null:/name}.
+    value: ${../../status/if/invalid-address:/name}
+  - description: |
+      There was no region associated with the identifier specified by
+      ${.:/params[0]/name}.
+    value: ${../../status/if/invalid-id:/name}
 type: interface