mirror of
https://git.rtems.org/rtems-docs/
synced 2025-07-02 06:00:16 +08:00
c-user: Split up region manager
This makes it easier to automatically generate parts of the manager documentation in the future. Update #3993.
This commit is contained in:
Sebastian Huber
parent
082054b63d
commit
aebb6fd7c7
@ -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
|
||||
|
||||
87
c-user/region/background.rst
Normal file
87
c-user/region/background.rst
Normal file
@ -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``.
|
||||
@ -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
|
||||
==========
|
||||
|
||||
15
c-user/region/index.rst
Normal file
15
c-user/region/index.rst
Normal file
@ -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
|
||||
29
c-user/region/introduction.rst
Normal file
29
c-user/region/introduction.rst
Normal file
@ -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`
|
||||
101
c-user/region/operations.rst
Normal file
101
c-user/region/operations.rst
Normal file
@ -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.
|
||||
Loading…
x
Reference in New Issue
Block a user