[rtems-central commit] spec: Update /rtems/region/* documentation
Sebastian Huber
sebh at rtems.org
Wed Apr 28 07:04:36 UTC 2021
Module: rtems-central
Branch: master
Commit: 59d09b1d770dea0fd190201d7ec38715ffca5bad
Changeset: http://git.rtems.org/rtems-central/commit/?id=59d09b1d770dea0fd190201d7ec38715ffca5bad
Author: Sebastian Huber <sebastian.huber at embedded-brains.de>
Date: Tue Apr 27 13:03:01 2021 +0200
spec: Update /rtems/region/* documentation
---
spec/rtems/message/if/receive.yml | 14 ++--
spec/rtems/region/if/create.yml | 2 +-
spec/rtems/region/if/extend.yml | 52 +++++++++---
spec/rtems/region/if/get-free-information.yml | 54 ++++++++++---
spec/rtems/region/if/get-information.yml | 52 +++++++++---
spec/rtems/region/if/get-segment-size.yml | 54 ++++++++++---
spec/rtems/region/if/get-segment.yml | 111 +++++++++++++++++++++++---
spec/rtems/region/if/group.yml | 18 +++++
spec/rtems/region/if/resize-segment.yml | 61 +++++++++++---
spec/rtems/region/if/return-segment.yml | 51 ++++++++++--
10 files changed, 394 insertions(+), 75 deletions(-)
diff --git a/spec/rtems/message/if/receive.yml b/spec/rtems/message/if/receive.yml
index 10a0d04..ac82193 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 4790e02..20992cd 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 c9b5835..b4c539a 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 0f81737..92f562f 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 e56db3a..e48cb4c 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 877f3d0..ca434ef 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 7f8f561..61fb016 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 158a3c3..a7795ff 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 f7b265d..396d2bc 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 e076ca9..c9b929a 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
More information about the vc
mailing list