spec: Update /rtems/region/* documentation

10 files changed, 394 insertions, 75 deletions

diff --git a/spec/rtems/message/if/receive.yml b/spec/rtems/message/if/receive.yml
index 10a0d049..ac821934 100644
--- a/spec/rtems/message/if/receive.yml
+++ b/spec/rtems/message/if/receive.yml
@@ -54,13 +54,13 @@ description: |
 
   If the calling task chooses to return immediately and the queue is empty,
   then the directive returns immediately with the
-  ${../../status/if/unsatisfied:/name} status cod.  If the calling task chooses
-  to wait at the message queue and the queue is empty, then the calling task is
-  placed on the message wait queue and blocked.  If the queue was created with
-  the ${../../attr/if/priority:/name} option specified, then the calling task
-  is inserted into the wait queue according to its priority.  But, if the queue
-  was created with the ${../../attr/if/fifo:/name} option specified, then the
-  calling task is placed at the rear of the wait queue.
+  ${../../status/if/unsatisfied:/name} status code.  If the calling task
+  chooses to wait at the message queue and the queue is empty, then the calling
+  task is placed on the message wait queue and blocked.  If the queue was
+  created with the ${../../attr/if/priority:/name} option specified, then the
+  calling task is inserted into the wait queue according to its priority.  But,
+  if the queue was created with the ${../../attr/if/fifo:/name} option
+  specified, then the calling task is placed at the rear of the wait queue.
 enabled-by: true
 index-entries:
 - receive message from a queue
diff --git a/spec/rtems/region/if/create.yml b/spec/rtems/region/if/create.yml
index 4790e027..20992cd7 100644
--- a/spec/rtems/region/if/create.yml
+++ b/spec/rtems/region/if/create.yml
@@ -27,7 +27,7 @@ description: |
   ${.:/params[1]/name} and is ${.:/params[2]/name} bytes long.  The memory area
   shall be large enough to contain some internal region administration data.
 
-  The **starting address and length of segments** allocated from the region
+  The **starting address** and **length of segments** allocated from the region
   will be an integral multiple of ${.:/params[3]/name}.  The specified page
   size will be aligned to an implementation-dependent minimum alignment if
   necessary.
diff --git a/spec/rtems/region/if/extend.yml b/spec/rtems/region/if/extend.yml
index c9b58354..b4c539a1 100644
--- a/spec/rtems/region/if/extend.yml
+++ b/spec/rtems/region/if/extend.yml
@@ -1,7 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Extends the region.
 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,61 @@ definition:
     - ${/c/if/uintptr_t:/name} ${.:/params[2]/name}
     return: ${../../status/if/code:/name}
   variants: []
-description: null
+description: |
+  This directive adds the memory area which starts at ${.:/params[1]/name} for
+  ${.:/params[2]/name} bytes to the region specified by ${.:/params[0]/name}.
 enabled-by: true
-index-entries: []
+index-entries:
+- add memory to a region
+- region, add memory
 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_extend
-notes: null
+notes: |
+  There are no alignment requirements for the memory area.  The memory area
+  must be big enough to contain some maintenance blocks.  It must not overlap
+  parts of the current heap memory areas.  Disconnected memory areas added to
+  the heap will lead to used blocks which cover the gaps.  Extending with an
+  inappropriate memory area will corrupt the heap resulting in undefined
+  behaviour.
 params:
-- description: '%'
+- description: |
+    is the region identifier.
   dir: null
   name: id
-- description: '%'
+- description: |
+    is the starting address of the memory area to extend the region.
   dir: null
   name: starting_address
-- description: '%'
+- description: |
+    is the length in bytes of the memory area to extend the region.
   dir: null
   name: length
 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}
+  - description: |
+      The memory area specified by ${.:/params[1]/name} and
+      ${.:/params[2]/name} was insufficient to extend the heap.
+    value: ${../../status/if/invalid-address:/name}
 type: interface
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
diff --git a/spec/rtems/region/if/get-information.yml b/spec/rtems/region/if/get-information.yml
index e56db3a9..e48cb4cc 100644
--- a/spec/rtems/region/if/get-information.yml
+++ b/spec/rtems/region/if/get-information.yml
@@ -1,7 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Gets the region 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,58 @@ 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 used and 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
 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_information
-notes: null
+notes: |
+  This is primarily intended as a mechanism to obtain a diagnostic information.
+  This method forms am O(n) scan of the free and an O(n) scan of the used
+  blocks 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.
+
+  To get only the free information of the region use
+  ${get-free-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 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
diff --git a/spec/rtems/region/if/get-segment-size.yml b/spec/rtems/region/if/get-segment-size.yml
index 877f3d03..ca434ef5 100644
--- a/spec/rtems/region/if/get-segment-size.yml
+++ b/spec/rtems/region/if/get-segment-size.yml
@@ -1,7 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Gets the size of the region segment.
 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,61 @@ definition:
     - ${/c/if/uintptr_t:/name} *${.:/params[2]/name}
     return: ${../../status/if/code:/name}
   variants: []
-description: null
+description: |
+  This directive obtains the size in bytes of the segment specified by
+  ${.:/params[1]/name} of the region specified by ${.:/params[0]/name} in
+  ${.:/params[2]/name}.
 enabled-by: true
-index-entries: []
+index-entries:
+- get size of segment
 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_segment_size
-notes: null
+notes: |
+  The actual length of the allocated segment may be larger than the requested
+  size because a segment size is always a multiple of the region's page size.
 params:
-- description: '%'
+- description: |
+    is the region identifier.
   dir: null
   name: id
-- description: '%'
+- description: |
+    is the begin address of the segment.
   dir: null
   name: segment
-- description: '%'
-  dir: null
+- description: |
+    is the pointer to a ${/c/if/uintptr_t:/name} variable.  When the directive
+    call is successful, the size of the segment in bytes will be stored in this
+    variable.
+  dir: out
   name: size
 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: |
+      The ${.:/params[2]/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}
+  - description: |
+      The segment was not within the region.
+    value: ${../../status/if/invalid-address:/name}
 type: interface
diff --git a/spec/rtems/region/if/get-segment.yml b/spec/rtems/region/if/get-segment.yml
index 7f8f5618..61fb0168 100644
--- a/spec/rtems/region/if/get-segment.yml
+++ b/spec/rtems/region/if/get-segment.yml
@@ -1,7 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Gets a segment from the region.
 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,122 @@ definition:
     - void **${.:/params[4]/name}
     return: ${../../status/if/code:/name}
   variants: []
-description: null
+description: |
+  This directive gets a segment from the region specified by
+  ${.:/params[0]/name}.
+
+  The **option set** specified in ${.:/params[2]/name} is built through a
+  *bitwise or* of the option constants described below.  Not all combinations
+  of options are allowed.  Some options are mutually exclusive.  If mutually
+  exclusive options are combined, the behaviour is undefined.  Options not
+  mentioned below are not evaluated by this directive and have no effect.
+  Default options can be selected by using the ${../../option/if/default:/name}
+  constant.
+
+  The calling task can **wait** or **try to get** a segment from the region
+  according to the mutually exclusive ${../../option/if/wait:/name} and
+  ${../../option/if/no-wait:/name} options.
+
+  * **Waiting to get** a segment from the region is the default and can be
+    emphasized through the use of the ${../../option/if/wait:/name} option.
+    The ${.:/params[3]/name} parameter defines how long the calling task is
+    willing to wait.  Use ${../../type/if/no-timeout:/name} to wait potentially
+    forever, otherwise set a timeout interval in clock ticks.
+
+  * **Trying to get** a segment from the region is selected by the
+    ${../../option/if/no-wait:/name} option.  If this option is defined, then
+    the ${.:/params[3]/name} parameter is ignored.  When a segment from the
+    region cannot be immediately allocated, then the
+    ${../../status/if/unsatisfied:/name} status is returned.
+
+  With either ${../../option/if/wait:/name} or ${../../option/if/no-wait:/name}
+  if there is a segment of the requested size is available, then it is returned
+  in ${.:/params[4]/name} and this directive returns immediately with the
+  ${../../status/if/successful:/name} status code.
+
+  If the calling task chooses to return immediately and the region has no
+  segment of the requested size available, then the directive returns
+  immediately with the ${../../status/if/unsatisfied:/name} status code.  If
+  the calling task chooses to wait for a segment, then the calling task is
+  placed on the region wait queue and blocked.  If the region was created with
+  the ${../../attr/if/priority:/name} option specified, then the calling task
+  is inserted into the wait queue according to its priority.  But, if the
+  region was created with the ${../../attr/if/fifo:/name} option specified,
+  then the calling task is placed at the rear of the wait queue.
 enabled-by: true
-index-entries: []
+index-entries:
+- get segment from region
 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/request-may-block
+- role: constraint
+  uid: /constraint/clock-tick
 name: rtems_region_get_segment
-notes: null
+notes: |
+  The actual length of the allocated segment may be larger than the requested
+  size because a segment size is always a multiple of the region's page size.
 params:
-- description: '%'
+- description: |
+    is the region identifier.
   dir: null
   name: id
-- description: '%'
+- description: |
+    is the size in bytes of the segment to allocate.
   dir: null
   name: size
-- description: '%'
+- description: |
+    is the option set.
   dir: null
   name: option_set
-- description: '%'
+- description: |
+    is the timeout in ${/glossary/clock-tick:/plural} if the
+    ${../../option/if/wait:/name} option is set.  Use
+    ${../../type/if/no-timeout:/name} to wait potentially forever.
   dir: null
   name: timeout
-- description: '%'
+- description: |
+    is the pointer to a void pointer variable.  When the directive call is
+    successful, the begin address of the allocated segment will be stored in
+    this variable.
+  dir: out
   dir: null
   name: segment
 return:
   return: null
-  return-values: []
+  return-values:
+  - description: |
+      The requested operation was successful.
+    value: ${../../status/if/successful:/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 zero.
+    value: ${../../status/if/invalid-size:/name}
+  - description: |
+      There was no region associated with the identifier specified by
+      ${.:/params[0]/name}.
+    value: ${../../status/if/invalid-id:/name}
+  - description: |
+      The ${.:/params[1]/name} parameter exceeded the maximum segment size
+      which is possible for the region.
+    value: ${../../status/if/invalid-size:/name}
+  - description: |
+      The region had no segment of the requested size immediately available.
+    value: ${../../status/if/unsatisfied:/name}
+  - description: |
+      The timeout happened while the calling task was waiting to get a segment
+      from the region.
+    value: ${../../status/if/timeout:/name}
 type: interface
diff --git a/spec/rtems/region/if/group.yml b/spec/rtems/region/if/group.yml
index 158a3c3c..a7795ff6 100644
--- a/spec/rtems/region/if/group.yml
+++ b/spec/rtems/region/if/group.yml
@@ -15,6 +15,24 @@ links:
   uid: header
 - role: interface-ingroup
   uid: ../../if/group
+- role: placement-order
+  uid: create
+- role: placement-order
+  uid: ident
+- role: placement-order
+  uid: delete
+- role: placement-order
+  uid: extend
+- role: placement-order
+  uid: get-segment
+- role: placement-order
+  uid: return-segment
+- role: placement-order
+  uid: resize-segment
+- role: placement-order
+  uid: get-information
+- role: placement-order
+  uid: get-free-information
 name: Region Manager
 text: |
   The Classic API shall provide an interface to the Region Manager.
diff --git a/spec/rtems/region/if/resize-segment.yml b/spec/rtems/region/if/resize-segment.yml
index f7b265d3..396d2bca 100644
--- a/spec/rtems/region/if/resize-segment.yml
+++ b/spec/rtems/region/if/resize-segment.yml
@@ -1,7 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Changes the size of the segment.
 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,69 @@ definition:
     - ${/c/if/uintptr_t:/name} *${.:/params[3]/name}
     return: ${../../status/if/code:/name}
   variants: []
-description: null
+description: |
+  This directive is used to increase or decrease the size of the
+  ${.:/params[1]/name} of the region specified by ${.:/params[0]/name}.  When
+  increasing the size of a segment, it is possible that there is no memory
+  available contiguous to the segment.  In this case, the request is
+  unsatisfied.
 enabled-by: true
-index-entries: []
+index-entries:
+- resize segment
 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_resize_segment
-notes: null
+notes: |
+  If an attempt to increase the size of a segment fails, then the application
+  may want to allocate a new segment of the desired size, copy the contents of
+  the original segment to the new, larger segment and then return the original
+  segment.
 params:
-- description: '%'
+- description: |
+    is the region identifier.
   dir: null
   name: id
-- description: '%'
+- description: |
+    is the begin address of the segment to resize.
   dir: null
   name: segment
-- description: '%'
+- description: |
+    is the requested new size of the segment.
   dir: null
   name: size
-- description: '%'
-  dir: null
+- description: |
+    is the pointer to an ${/c/if/uintptr_t:/name} variable.  When the directive
+    call is successful, the old size of the segment will be stored in this
+    variable.
+  dir: out
   name: old_size
 return:
   return: null
-  return-values: []
+  return-values:
+  - description: |
+      The requested operation was successful.
+    value: ${../../status/if/successful:/name}
+  - description: |
+      The ${.:/params[3]/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}
+  - description: |
+      The segment was not within the region.
+    value: ${../../status/if/invalid-address:/name}
+  - description: |
+      The region was unable to resize the segment.
+    value: ${../../status/if/unsatisfied:/name}
 type: interface
diff --git a/spec/rtems/region/if/return-segment.yml b/spec/rtems/region/if/return-segment.yml
index e076ca94..c9b929a7 100644
--- a/spec/rtems/region/if/return-segment.yml
+++ b/spec/rtems/region/if/return-segment.yml
@@ -1,7 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Returns the segment to the region.
 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,59 @@ definition:
     - void *${.:/params[1]/name}
     return: ${../../status/if/code:/name}
   variants: []
-description: null
+description: |
+  This directive returns the segment specified by ${.:/params[1]/name} to the
+  region specified by ${.:/params[0]/name}.  The returned segment is merged
+  with its neighbors to form the largest possible segment.  The first task on
+  the wait queue is examined to determine if its segment request can now be
+  satisfied.  If so, it is given a segment and unblocked.  This process is
+  repeated until the first task's segment request cannot be satisfied.
 enabled-by: true
-index-entries: []
+index-entries:
+- return segment to region
 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/unblock-may-preempt
+- role: constraint
+  uid: /constraint/object-allocator
 name: rtems_region_return_segment
-notes: null
+notes: |
+  This directive will cause the calling task to be preempted if one or more
+  local tasks are waiting for a segment and the following conditions exist:
+
+  * A waiting task has a higher priority than the calling task.
+
+  * The size of the segment required by the waiting task is less than or equal
+    to the size of the segment returned.
 params:
-- description: '%'
+- description: |
+    is the region identifier.
   dir: null
   name: id
-- description: '%'
+- description: |
+    is the begin address of the segment to return.
   dir: null
   name: segment
 return:
   return: null
-  return-values: []
+  return-values:
+  - description: |
+      The requested operation was successful.
+    value: ${../../status/if/successful:/name}
+  - description: |
+      There was no region associated with the identifier specified by
+      ${.:/params[0]/name}.
+    value: ${../../status/if/invalid-id:/name}
+  - description: |
+      The segment was not within the region.
+    value: ${../../status/if/invalid-address:/name}
 type: interface