summaryrefslogtreecommitdiffstats
path: root/doc/user/region.t
diff options
context:
space:
mode:
authorJoel Sherrill <joel.sherrill@OARcorp.com>2005-06-17 14:29:13 +0000
committerJoel Sherrill <joel.sherrill@OARcorp.com>2005-06-17 14:29:13 +0000
commita9d5d449a14b0dd357503e9d5f37cc88ffa2bdbf (patch)
tree5b7263eccf1691f7ec468f3d851c6628fa6caff5 /doc/user/region.t
parentdf8ba46d8e967351eb1ddb8e35ac53458e6ba444 (diff)
downloadrtems-a9d5d449a14b0dd357503e9d5f37cc88ffa2bdbf.tar.bz2
2005-06-17 Joel Sherrill <joel@OARcorp.com>
* user/region.t: Add documentation on region_resize_segment.
Diffstat (limited to '')
-rw-r--r--doc/user/region.t67
1 files changed, 67 insertions, 0 deletions
diff --git a/doc/user/region.t b/doc/user/region.t
index 4b90443049..b11cf1c2ae 100644
--- a/doc/user/region.t
+++ b/doc/user/region.t
@@ -24,6 +24,7 @@ provided by the region manager are:
@item @code{@value{DIRPREFIX}region_get_segment} - Get segment from a region
@item @code{@value{DIRPREFIX}region_return_segment} - Return segment to a region
@item @code{@value{DIRPREFIX}region_get_segment_size} - Obtain size of a segment
+@item @code{@value{DIRPREFIX}region_resize_segment} - Change size of a segment
@end itemize
@section Background
@@ -202,6 +203,15 @@ size in bytes of the specified segment. The size returned
includes any "extra" memory included in the segment because of
rounding up to a page size boundary.
+@subsection Changing the Size of a Segment
+
+The @code{@value{DIRPREFIX}region_resize_segment} directive
+is used to change the size in bytes of the specified segment. The
+size may be increased or decreased. When increasing the
+size of a segment, it is possible that the request cannot be
+satisfied. This directive is used to support the @code{realloc()}
+function in the Standard C Library.
+
@subsection Deleting a Region
A region can be removed from the system and returned
@@ -663,3 +673,60 @@ 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.
+@c
+@c
+@c
+@page
+@subsection REGION_RESIZE_SEGMENT - Change size of a segment
+
+@cindex resize segment
+
+@subheading CALLING SEQUENCE:
+
+@ifset is-C
+@findex rtems_region_resize_segment
+@example
+rtems_status_code rtems_region_resize_segment(
+ rtems_id id,
+ void *segment,
+ size_t size,
+ size_t *old_size
+);
+@end example
+@end ifset
+
+@ifset is-Ada
+@example
+procedure Region_Resize_Segment (
+ ID : in RTEMS.ID;
+ Segment : in RTEMS.Address;
+ Size : in RTEMS.Unsigned32;
+ Old_Size : out RTEMS.Unsigned32;
+ Result : out RTEMS.Status_Codes
+);
+@end example
+@end ifset
+
+@subheading DIRECTIVE STATUS CODES:
+
+@code{@value{RPREFIX}SUCCESSFUL} - segment obtained successfully@*
+@code{@value{RPREFIX}INVALID_ADDRESS} - @code{segment} is NULL@*
+@code{@value{RPREFIX}INVALID_ADDRESS} - @code{old_size} is NULL@*
+@code{@value{RPREFIX}INVALID_ID} - invalid region id@*
+@code{@value{RPREFIX}INVALID_ADDRESS} - segment address not in region
+@code{@value{RPREFIX}UNSATISFIED} - unable to make segment larger
+
+@subheading DESCRIPTION:
+
+This directive is used to increase or decrease the size of
+a @a{segment}. When increasing the size of a segment, it
+is possible that there is not memory available contiguous
+to the segment. In this case, the request is unsatisfied.
+
+@subheading NOTES:
+
+If an attempt to increase the size of a @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.
+