[PATCH v2 11/16] c-user: Split up region manager
Sebastian Huber
sebastian.huber at embedded-brains.de
Wed Sep 2 16:01:05 UTC 2020
This makes it easier to automatically generate parts of the manager
documentation in the future.
Update #3993.
---
c-user/index.rst | 2 +-
c-user/region/background.rst | 87 +++++++
.../directives.rst} | 213 ------------------
c-user/region/index.rst | 15 ++
c-user/region/introduction.rst | 29 +++
c-user/region/operations.rst | 101 +++++++++
6 files changed, 233 insertions(+), 214 deletions(-)
create mode 100644 c-user/region/background.rst
rename c-user/{region_manager.rst => region/directives.rst} (66%)
create mode 100644 c-user/region/index.rst
create mode 100644 c-user/region/introduction.rst
create mode 100644 c-user/region/operations.rst
diff --git a/c-user/index.rst b/c-user/index.rst
index 4cf9e32..7bd6017 100644
--- a/c-user/index.rst
+++ b/c-user/index.rst
@@ -41,7 +41,7 @@ RTEMS Classic API Guide (|version|).
event/index
signal_manager
partition/index
- region_manager
+ region/index
dual-ported-memory/index
io/index
fatal_error
diff --git a/c-user/region/background.rst b/c-user/region/background.rst
new file mode 100644
index 0000000..cf22a76
--- /dev/null
+++ b/c-user/region/background.rst
@@ -0,0 +1,87 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+
+Background
+==========
+
+.. index:: region, definition
+.. index:: segment, definition
+
+Region Manager Definitions
+--------------------------
+
+A region makes up a physically contiguous memory space with user-defined
+boundaries from which variable-sized segments are dynamically allocated and
+deallocated. A segment is a variable size section of memory which is allocated
+in multiples of a user-defined page size. This page size is required to be a
+multiple of four greater than or equal to four. For example, if a request for
+a 350-byte segment is made in a region with 256-byte pages, then a 512-byte
+segment is allocated.
+
+Regions are organized as doubly linked chains of variable sized memory blocks.
+Memory requests are allocated using a first-fit algorithm. If available, the
+requester receives the number of bytes requested (rounded up to the next page
+size). RTEMS requires some overhead from the region's memory for each segment
+that is allocated. Therefore, an application should only modify the memory of
+a segment that has been obtained from the region. The application should NOT
+modify the memory outside of any obtained segments and within the region's
+boundaries while the region is currently active in the system.
+
+Upon return to the region, the free block is coalesced with its neighbors (if
+free) on both sides to produce the largest possible unused block.
+
+.. index:: region attribute set, building
+
+Building an Attribute Set
+-------------------------
+
+In general, an attribute set is built by a bitwise OR of the desired attribute
+components. The set of valid region attributes is provided in the following
+table:
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``RTEMS_FIFO``
+ - tasks wait by FIFO (default)
+ * - ``RTEMS_PRIORITY``
+ - tasks wait by priority
+
+Attribute values are specifically designed to be mutually exclusive, therefore
+bitwise OR and addition operations are equivalent as long as each attribute
+appears exactly once in the component list. An attribute listed as a default
+is not required to appear in the attribute list, although it is a good
+programming practice to specify default attributes. If all defaults are
+desired, the attribute ``RTEMS_DEFAULT_ATTRIBUTES`` should be specified on this
+call.
+
+This example demonstrates the attribute_set parameter needed to create a region
+with the task priority waiting queue discipline. The attribute_set parameter
+to the ``rtems_region_create`` directive should be ``RTEMS_PRIORITY``.
+
+Building an Option Set
+----------------------
+
+In general, an option is built by a bitwise OR of the desired option
+components. The set of valid options for the ``rtems_region_get_segment``
+directive are listed in the following table:
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``RTEMS_WAIT``
+ - task will wait for segment (default)
+ * - ``RTEMS_NO_WAIT``
+ - task should not wait
+
+Option values are specifically designed to be mutually exclusive, therefore
+bitwise OR and addition operations are equivalent as long as each option
+appears exactly once in the component list. An option listed as a default is
+not required to appear in the option list, although it is a good programming
+practice to specify default options. If all defaults are desired, the
+option ``RTEMS_DEFAULT_OPTIONS`` should be specified on this call.
+
+This example demonstrates the option parameter needed to poll for a segment.
+The option parameter passed to the ``rtems_region_get_segment`` directive
+should be ``RTEMS_NO_WAIT``.
diff --git a/c-user/region_manager.rst b/c-user/region/directives.rst
similarity index 66%
rename from c-user/region_manager.rst
rename to c-user/region/directives.rst
index f9cfb46..be994f6 100644
--- a/c-user/region_manager.rst
+++ b/c-user/region/directives.rst
@@ -2,219 +2,6 @@
.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
-.. index:: regions
-
-Region Manager
-**************
-
-Introduction
-============
-
-The region manager provides facilities to dynamically allocate memory in
-variable sized units. The directives provided by the region manager are:
-
-- rtems_region_create_ - Create a region
-
-- rtems_region_ident_ - Get ID of a region
-
-- rtems_region_delete_ - Delete a region
-
-- rtems_region_extend_ - Add memory to a region
-
-- rtems_region_get_segment_ - Get segment from a region
-
-- rtems_region_return_segment_ - Return segment to a region
-
-- rtems_region_get_segment_size_ - Obtain size of a segment
-
-- rtems_region_resize_segment_ - Change size of a segment
-
-- rtems_region_get_information_ - Get region information
-
-- rtems_region_get_free_information_ - Get region free information
-
-Background
-==========
-
-.. index:: region, definition
-.. index:: segment, definition
-
-Region Manager Definitions
---------------------------
-
-A region makes up a physically contiguous memory space with user-defined
-boundaries from which variable-sized segments are dynamically allocated and
-deallocated. A segment is a variable size section of memory which is allocated
-in multiples of a user-defined page size. This page size is required to be a
-multiple of four greater than or equal to four. For example, if a request for
-a 350-byte segment is made in a region with 256-byte pages, then a 512-byte
-segment is allocated.
-
-Regions are organized as doubly linked chains of variable sized memory blocks.
-Memory requests are allocated using a first-fit algorithm. If available, the
-requester receives the number of bytes requested (rounded up to the next page
-size). RTEMS requires some overhead from the region's memory for each segment
-that is allocated. Therefore, an application should only modify the memory of
-a segment that has been obtained from the region. The application should NOT
-modify the memory outside of any obtained segments and within the region's
-boundaries while the region is currently active in the system.
-
-Upon return to the region, the free block is coalesced with its neighbors (if
-free) on both sides to produce the largest possible unused block.
-
-.. index:: region attribute set, building
-
-Building an Attribute Set
--------------------------
-
-In general, an attribute set is built by a bitwise OR of the desired attribute
-components. The set of valid region attributes is provided in the following
-table:
-
-.. list-table::
- :class: rtems-table
-
- * - ``RTEMS_FIFO``
- - tasks wait by FIFO (default)
- * - ``RTEMS_PRIORITY``
- - tasks wait by priority
-
-Attribute values are specifically designed to be mutually exclusive, therefore
-bitwise OR and addition operations are equivalent as long as each attribute
-appears exactly once in the component list. An attribute listed as a default
-is not required to appear in the attribute list, although it is a good
-programming practice to specify default attributes. If all defaults are
-desired, the attribute ``RTEMS_DEFAULT_ATTRIBUTES`` should be specified on this
-call.
-
-This example demonstrates the attribute_set parameter needed to create a region
-with the task priority waiting queue discipline. The attribute_set parameter
-to the ``rtems_region_create`` directive should be ``RTEMS_PRIORITY``.
-
-Building an Option Set
-----------------------
-
-In general, an option is built by a bitwise OR of the desired option
-components. The set of valid options for the ``rtems_region_get_segment``
-directive are listed in the following table:
-
-.. list-table::
- :class: rtems-table
-
- * - ``RTEMS_WAIT``
- - task will wait for segment (default)
- * - ``RTEMS_NO_WAIT``
- - task should not wait
-
-Option values are specifically designed to be mutually exclusive, therefore
-bitwise OR and addition operations are equivalent as long as each option
-appears exactly once in the component list. An option listed as a default is
-not required to appear in the option list, although it is a good programming
-practice to specify default options. If all defaults are desired, the
-option ``RTEMS_DEFAULT_OPTIONS`` should be specified on this call.
-
-This example demonstrates the option parameter needed to poll for a segment.
-The option parameter passed to the ``rtems_region_get_segment`` directive
-should be ``RTEMS_NO_WAIT``.
-
-Operations
-==========
-
-Creating a Region
------------------
-
-The ``rtems_region_create`` directive creates a region with the user-defined
-name. The user may select FIFO or task priority as the method for placing
-waiting tasks in the task wait queue. RTEMS allocates a Region Control Block
-(RNCB) from the RNCB free list to maintain the newly created region. RTEMS
-also generates a unique region ID which is returned to the calling task.
-
-It is not possible to calculate the exact number of bytes available to the user
-since RTEMS requires overhead for each segment allocated. For example, a
-region with one segment that is the size of the entire region has more
-available bytes than a region with two segments that collectively are the size
-of the entire region. This is because the region with one segment requires
-only the overhead for one segment, while the other region requires the overhead
-for two segments.
-
-Due to automatic coalescing, the number of segments in the region dynamically
-changes. Therefore, the total overhead required by RTEMS dynamically changes.
-
-Obtaining Region IDs
---------------------
-
-When a region is created, RTEMS generates a unique region ID and assigns it to
-the created region until it is deleted. The region ID may be obtained by
-either of two methods. First, as the result of an invocation of the
-``rtems_region_create`` directive, the region ID is stored in a user provided
-location. Second, the region ID may be obtained later using the
-``rtems_region_ident`` directive. The region ID is used by other region
-manager directives to access this region.
-
-Adding Memory to a Region
--------------------------
-
-The ``rtems_region_extend`` directive may be used to add memory to an existing
-region. The caller specifies the size in bytes and starting address of the
-memory being added.
-
-Acquiring a Segment
--------------------
-
-The ``rtems_region_get_segment`` directive attempts to acquire a segment from a
-specified region. If the region has enough available free memory, then a
-segment is returned successfully to the caller. When the segment cannot be
-allocated, one of the following situations applies:
-
-- By default, the calling task will wait forever to acquire the segment.
-
-- Specifying the ``RTEMS_NO_WAIT`` option forces an immediate return with an
- error status code.
-
-- Specifying a timeout limits the interval the task will wait before returning
- with an error status code.
-
-If the task waits for the segment, then it is placed in the region's task wait
-queue in either FIFO or task priority order. All tasks waiting on a region are
-returned an error when the message queue is deleted.
-
-Releasing a Segment
--------------------
-
-When a segment is returned to a region by the ``rtems_region_return_segment``
-directive, it is merged with its unallocated 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.
-
-Obtaining the Size of a Segment
--------------------------------
-
-The ``rtems_region_get_segment_size`` directive returns the 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.
-
-Changing the Size of a Segment
-------------------------------
-
-The ``rtems_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 provides functionality similar to the ``realloc()``
-function in the Standard C Library.
-
-Deleting a Region
------------------
-
-A region can be removed from the system and returned to RTEMS with the
-``rtems_region_delete`` directive. When a region is deleted, its control block
-is returned to the RNCB free list. A region with segments still allocated is
-not allowed to be deleted. Any task attempting to do so will be returned an
-error. As a result of this directive, all tasks blocked waiting to obtain a
-segment from the region will be readied and returned a status code which
-indicates that the region was deleted.
-
Directives
==========
diff --git a/c-user/region/index.rst b/c-user/region/index.rst
new file mode 100644
index 0000000..90560a8
--- /dev/null
+++ b/c-user/region/index.rst
@@ -0,0 +1,15 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+
+.. index:: regions
+
+Region Manager
+**************
+
+.. toctree::
+
+ introduction
+ background
+ operations
+ directives
diff --git a/c-user/region/introduction.rst b/c-user/region/introduction.rst
new file mode 100644
index 0000000..418e397
--- /dev/null
+++ b/c-user/region/introduction.rst
@@ -0,0 +1,29 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+
+Introduction
+============
+
+The region manager provides facilities to dynamically allocate memory in
+variable sized units. The directives provided by the region manager are:
+
+- :ref:`rtems_region_create`
+
+- :ref:`rtems_region_ident`
+
+- :ref:`rtems_region_delete`
+
+- :ref:`rtems_region_extend`
+
+- :ref:`rtems_region_get_segment`
+
+- :ref:`rtems_region_return_segment`
+
+- :ref:`rtems_region_get_segment_size`
+
+- :ref:`rtems_region_resize_segment`
+
+- :ref:`rtems_region_get_information`
+
+- :ref:`rtems_region_get_free_information`
diff --git a/c-user/region/operations.rst b/c-user/region/operations.rst
new file mode 100644
index 0000000..ef41d39
--- /dev/null
+++ b/c-user/region/operations.rst
@@ -0,0 +1,101 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+
+Operations
+==========
+
+Creating a Region
+-----------------
+
+The ``rtems_region_create`` directive creates a region with the user-defined
+name. The user may select FIFO or task priority as the method for placing
+waiting tasks in the task wait queue. RTEMS allocates a Region Control Block
+(RNCB) from the RNCB free list to maintain the newly created region. RTEMS
+also generates a unique region ID which is returned to the calling task.
+
+It is not possible to calculate the exact number of bytes available to the user
+since RTEMS requires overhead for each segment allocated. For example, a
+region with one segment that is the size of the entire region has more
+available bytes than a region with two segments that collectively are the size
+of the entire region. This is because the region with one segment requires
+only the overhead for one segment, while the other region requires the overhead
+for two segments.
+
+Due to automatic coalescing, the number of segments in the region dynamically
+changes. Therefore, the total overhead required by RTEMS dynamically changes.
+
+Obtaining Region IDs
+--------------------
+
+When a region is created, RTEMS generates a unique region ID and assigns it to
+the created region until it is deleted. The region ID may be obtained by
+either of two methods. First, as the result of an invocation of the
+``rtems_region_create`` directive, the region ID is stored in a user provided
+location. Second, the region ID may be obtained later using the
+``rtems_region_ident`` directive. The region ID is used by other region
+manager directives to access this region.
+
+Adding Memory to a Region
+-------------------------
+
+The ``rtems_region_extend`` directive may be used to add memory to an existing
+region. The caller specifies the size in bytes and starting address of the
+memory being added.
+
+Acquiring a Segment
+-------------------
+
+The ``rtems_region_get_segment`` directive attempts to acquire a segment from a
+specified region. If the region has enough available free memory, then a
+segment is returned successfully to the caller. When the segment cannot be
+allocated, one of the following situations applies:
+
+- By default, the calling task will wait forever to acquire the segment.
+
+- Specifying the ``RTEMS_NO_WAIT`` option forces an immediate return with an
+ error status code.
+
+- Specifying a timeout limits the interval the task will wait before returning
+ with an error status code.
+
+If the task waits for the segment, then it is placed in the region's task wait
+queue in either FIFO or task priority order. All tasks waiting on a region are
+returned an error when the message queue is deleted.
+
+Releasing a Segment
+-------------------
+
+When a segment is returned to a region by the ``rtems_region_return_segment``
+directive, it is merged with its unallocated 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.
+
+Obtaining the Size of a Segment
+-------------------------------
+
+The ``rtems_region_get_segment_size`` directive returns the 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.
+
+Changing the Size of a Segment
+------------------------------
+
+The ``rtems_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 provides functionality similar to the ``realloc()``
+function in the Standard C Library.
+
+Deleting a Region
+-----------------
+
+A region can be removed from the system and returned to RTEMS with the
+``rtems_region_delete`` directive. When a region is deleted, its control block
+is returned to the RNCB free list. A region with segments still allocated is
+not allowed to be deleted. Any task attempting to do so will be returned an
+error. As a result of this directive, all tasks blocked waiting to obtain a
+segment from the region will be readied and returned a status code which
+indicates that the region was deleted.
--
2.26.2
More information about the devel
mailing list