mirror of
https://git.rtems.org/rtems-docs/
synced 2025-06-10 16:12:09 +08:00
aebb6fd7c7
This makes it easier to automatically generate parts of the manager documentation in the future. Update #3993.
562 lines
17 KiB
ReStructuredText
562 lines
17 KiB
ReStructuredText
.. SPDX-License-Identifier: CC-BY-SA-4.0
|
|
|
|
.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
|
|
|
|
Directives
|
|
==========
|
|
|
|
This section details the region manager's directives. A subsection is
|
|
dedicated to each of this manager's directives and describes the calling
|
|
sequence, related constants, usage, and status codes.
|
|
|
|
.. raw:: latex
|
|
|
|
\clearpage
|
|
|
|
.. index:: create a region
|
|
|
|
.. _rtems_region_create:
|
|
|
|
REGION_CREATE - Create a region
|
|
-------------------------------
|
|
|
|
CALLING SEQUENCE:
|
|
.. code-block:: c
|
|
|
|
rtems_status_code rtems_region_create(
|
|
rtems_name name,
|
|
void *starting_address,
|
|
uintptr_t length,
|
|
uintptr_t page_size,
|
|
rtems_attribute attribute_set,
|
|
rtems_id *id
|
|
);
|
|
|
|
DIRECTIVE STATUS CODES:
|
|
.. list-table::
|
|
:class: rtems-table
|
|
|
|
* - ``RTEMS_SUCCESSFUL``
|
|
- region created successfully
|
|
* - ``RTEMS_INVALID_NAME``
|
|
- invalid region name
|
|
* - ``RTEMS_INVALID_ADDRESS``
|
|
- ``id`` is NULL
|
|
* - ``RTEMS_INVALID_ADDRESS``
|
|
- ``starting_address`` is NULL
|
|
* - ``RTEMS_TOO_MANY``
|
|
- too many regions created
|
|
* - ``RTEMS_INVALID_SIZE``
|
|
- invalid page size
|
|
* - ``RTEMS_INVALID_SIZE``
|
|
- the memory area defined by the starting address and the length
|
|
parameters is too small
|
|
|
|
DESCRIPTION:
|
|
This directive creates a region from a contiguous memory area
|
|
which starts at starting_address and is length bytes long. The memory area
|
|
must be large enough to contain some internal region administration data.
|
|
Segments allocated from the region will be a multiple of page_size bytes in
|
|
length. The specified page size will be aligned to an
|
|
architecture-specific minimum alignment if necessary.
|
|
|
|
The assigned region id is returned in id. This region id is used as an
|
|
argument to other region related directives to access the region.
|
|
|
|
For control and maintenance of the region, RTEMS allocates and initializes
|
|
an RNCB from the RNCB free pool. Thus memory from the region is not used
|
|
to store the RNCB. However, some overhead within the region is required by
|
|
RTEMS each time a segment is constructed in the region.
|
|
|
|
Specifying ``RTEMS_PRIORITY`` in attribute_set causes tasks waiting for a
|
|
segment to be serviced according to task priority. Specifying
|
|
``RTEMS_FIFO`` in attribute_set or selecting ``RTEMS_DEFAULT_ATTRIBUTES``
|
|
will cause waiting tasks to be serviced in First In-First Out order.
|
|
|
|
NOTES:
|
|
This directive will obtain the allocator mutex and may cause the calling
|
|
task to be preempted.
|
|
|
|
The following region attribute constants are defined by RTEMS:
|
|
|
|
.. list-table::
|
|
:class: rtems-table
|
|
|
|
* - ``RTEMS_FIFO``
|
|
- tasks wait by FIFO (default)
|
|
* - ``RTEMS_PRIORITY``
|
|
- tasks wait by priority
|
|
|
|
.. raw:: latex
|
|
|
|
\clearpage
|
|
|
|
.. index:: get ID of a region
|
|
.. index:: obtain ID of a region
|
|
.. index:: rtems_region_ident
|
|
|
|
.. _rtems_region_ident:
|
|
|
|
REGION_IDENT - Get ID of a region
|
|
---------------------------------
|
|
|
|
CALLING SEQUENCE:
|
|
.. code-block:: c
|
|
|
|
rtems_status_code rtems_region_ident(
|
|
rtems_name name,
|
|
rtems_id *id
|
|
);
|
|
|
|
DIRECTIVE STATUS CODES:
|
|
.. list-table::
|
|
:class: rtems-table
|
|
|
|
* - ``RTEMS_SUCCESSFUL``
|
|
- region identified successfully
|
|
* - ``RTEMS_INVALID_ADDRESS``
|
|
- ``id`` is NULL
|
|
* - ``RTEMS_INVALID_NAME``
|
|
- region name not found
|
|
|
|
DESCRIPTION:
|
|
|
|
This directive obtains the region id associated with the region name to be
|
|
acquired. If the region name is not unique, then the region id will match
|
|
one of the regions with that name. However, this region id is not
|
|
guaranteed to correspond to the desired region. The region id is used to
|
|
access this region in other region manager directives.
|
|
|
|
NOTES:
|
|
This directive will not cause the running task to be preempted.
|
|
|
|
.. raw:: latex
|
|
|
|
\clearpage
|
|
|
|
.. index:: delete a region
|
|
.. index:: rtems_region_delete
|
|
|
|
.. _rtems_region_delete:
|
|
|
|
REGION_DELETE - Delete a region
|
|
-------------------------------
|
|
|
|
CALLING SEQUENCE:
|
|
.. code-block:: c
|
|
|
|
rtems_status_code rtems_region_delete(
|
|
rtems_id id
|
|
);
|
|
|
|
DIRECTIVE STATUS CODES:
|
|
.. list-table::
|
|
:class: rtems-table
|
|
|
|
* - ``RTEMS_SUCCESSFUL``
|
|
- region deleted successfully
|
|
* - ``RTEMS_INVALID_ID``
|
|
- invalid region id
|
|
* - ``RTEMS_RESOURCE_IN_USE``
|
|
- segments still in use
|
|
|
|
DESCRIPTION:
|
|
This directive deletes the region specified by id. The region cannot be
|
|
deleted if any of its segments are still allocated. The RNCB for the
|
|
deleted region is reclaimed by RTEMS.
|
|
|
|
NOTES:
|
|
This directive will obtain the allocator mutex and may cause the calling
|
|
task to be preempted.
|
|
|
|
The calling task does not have to be the task that created the region. Any
|
|
local task that knows the region id can delete the region.
|
|
|
|
.. raw:: latex
|
|
|
|
\clearpage
|
|
|
|
.. index:: add memory to a region
|
|
.. index:: region, add memory
|
|
.. index:: rtems_region_extend
|
|
|
|
.. _rtems_region_extend:
|
|
|
|
REGION_EXTEND - Add memory to a region
|
|
--------------------------------------
|
|
|
|
CALLING SEQUENCE:
|
|
.. code-block:: c
|
|
|
|
rtems_status_code rtems_region_extend(
|
|
rtems_id id,
|
|
void *starting_address,
|
|
uintptr_t length
|
|
);
|
|
|
|
DIRECTIVE STATUS CODES:
|
|
.. list-table::
|
|
:class: rtems-table
|
|
|
|
* - ``RTEMS_SUCCESSFUL``
|
|
- region extended successfully
|
|
* - ``RTEMS_INVALID_ADDRESS``
|
|
- ``starting_address`` is NULL
|
|
* - ``RTEMS_INVALID_ID``
|
|
- invalid region id
|
|
* - ``RTEMS_INVALID_ADDRESS``
|
|
- invalid address of area to add
|
|
|
|
DESCRIPTION:
|
|
This directive adds the memory area which starts at
|
|
:c:data:`starting_address` for :c:data:`length` bytes to the region
|
|
specified by :c:data:`id`.
|
|
|
|
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.
|
|
|
|
NOTES:
|
|
This directive will obtain the allocator mutex and may cause the calling
|
|
task to be preempted.
|
|
|
|
The calling task does not have to be the task that created the region. Any
|
|
local task that knows the region identifier can extend the region.
|
|
|
|
.. raw:: latex
|
|
|
|
\clearpage
|
|
|
|
.. index:: get segment from region
|
|
.. index:: rtems_region_get_segment
|
|
|
|
.. _rtems_region_get_segment:
|
|
|
|
REGION_GET_SEGMENT - Get segment from a region
|
|
----------------------------------------------
|
|
|
|
CALLING SEQUENCE:
|
|
.. code-block:: c
|
|
|
|
rtems_status_code rtems_region_get_segment(
|
|
rtems_id id,
|
|
uintptr_t size,
|
|
rtems_option option_set,
|
|
rtems_interval timeout,
|
|
void **segment
|
|
);
|
|
|
|
DIRECTIVE STATUS CODES:
|
|
.. list-table::
|
|
:class: rtems-table
|
|
|
|
* - ``RTEMS_SUCCESSFUL``
|
|
- segment obtained successfully
|
|
* - ``RTEMS_INVALID_ADDRESS``
|
|
- ``segment`` is NULL
|
|
* - ``RTEMS_INVALID_ID``
|
|
- invalid region id
|
|
* - ``RTEMS_INVALID_SIZE``
|
|
- request is for zero bytes or exceeds the size of maximum segment which is
|
|
possible for this region
|
|
* - ``RTEMS_UNSATISFIED``
|
|
- segment of requested size not available
|
|
* - ``RTEMS_TIMEOUT``
|
|
- timed out waiting for segment
|
|
* - ``RTEMS_OBJECT_WAS_DELETED``
|
|
- region deleted while waiting
|
|
|
|
DESCRIPTION:
|
|
This directive obtains a variable size segment from the region specified by
|
|
``id``. The address of the allocated segment is returned in segment. The
|
|
``RTEMS_WAIT`` and ``RTEMS_NO_WAIT`` components of the options parameter
|
|
are used to specify whether the calling tasks wish to wait for a segment to
|
|
become available or return immediately if no segment is available. For
|
|
either option, if a sufficiently sized segment is available, then the
|
|
segment is successfully acquired by returning immediately with the
|
|
``RTEMS_SUCCESSFUL`` status code.
|
|
|
|
If the calling task chooses to return immediately and a segment large
|
|
enough is not available, then an error code indicating this fact is
|
|
returned. If the calling task chooses to wait for the segment and a
|
|
segment large enough is not available, then the calling task is placed on
|
|
the region's segment wait queue and blocked. If the region was created
|
|
with the ``RTEMS_PRIORITY`` option, then the calling task is inserted into
|
|
the wait queue according to its priority. However, if the region was
|
|
created with the ``RTEMS_FIFO`` option, then the calling task is placed at
|
|
the rear of the wait queue.
|
|
|
|
The timeout parameter specifies the maximum interval that a task is willing
|
|
to wait to obtain a segment. If timeout is set to ``RTEMS_NO_TIMEOUT``,
|
|
then the calling task will wait forever.
|
|
|
|
NOTES:
|
|
This directive will obtain the allocator mutex and may cause the calling
|
|
task to be preempted.
|
|
|
|
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.
|
|
|
|
The following segment acquisition option constants are defined by RTEMS:
|
|
|
|
.. list-table::
|
|
:class: rtems-table
|
|
|
|
* - ``RTEMS_WAIT``
|
|
- task will wait for segment (default)
|
|
* - ``RTEMS_NO_WAIT``
|
|
- task should not wait
|
|
|
|
A clock tick is required to support the timeout functionality of this
|
|
directive.
|
|
|
|
.. raw:: latex
|
|
|
|
\clearpage
|
|
|
|
.. index:: return segment to region
|
|
.. index:: rtems_region_return_segment
|
|
|
|
.. _rtems_region_return_segment:
|
|
|
|
REGION_RETURN_SEGMENT - Return segment to a region
|
|
--------------------------------------------------
|
|
|
|
CALLING SEQUENCE:
|
|
.. code-block:: c
|
|
|
|
rtems_status_code rtems_region_return_segment(
|
|
rtems_id id,
|
|
void *segment
|
|
);
|
|
|
|
DIRECTIVE STATUS CODES:
|
|
.. list-table::
|
|
:class: rtems-table
|
|
|
|
* - ``RTEMS_SUCCESSFUL``
|
|
- segment returned successfully
|
|
* - ``RTEMS_INVALID_ADDRESS``
|
|
- ``segment`` is NULL
|
|
* - ``RTEMS_INVALID_ID``
|
|
- invalid region id
|
|
* - ``RTEMS_INVALID_ADDRESS``
|
|
- segment address not in region
|
|
|
|
DESCRIPTION:
|
|
This directive returns the segment specified by segment to the region
|
|
specified by id. 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.
|
|
|
|
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.
|
|
|
|
.. raw:: latex
|
|
|
|
\clearpage
|
|
|
|
.. index:: get size of segment
|
|
.. index:: rtems_region_get_segment_size
|
|
|
|
.. _rtems_region_get_segment_size:
|
|
|
|
REGION_GET_SEGMENT_SIZE - Obtain size of a segment
|
|
--------------------------------------------------
|
|
|
|
CALLING SEQUENCE:
|
|
.. code-block:: c
|
|
|
|
rtems_status_code rtems_region_get_segment_size(
|
|
rtems_id id,
|
|
void *segment,
|
|
uintptr_t *size
|
|
);
|
|
|
|
DIRECTIVE STATUS CODES:
|
|
.. list-table::
|
|
:class: rtems-table
|
|
|
|
* - ``RTEMS_SUCCESSFUL``
|
|
- segment obtained successfully
|
|
* - ``RTEMS_INVALID_ADDRESS``
|
|
- ``segment`` is NULL
|
|
* - ``RTEMS_INVALID_ADDRESS``
|
|
- ``size`` is NULL
|
|
* - ``RTEMS_INVALID_ID``
|
|
- invalid region id
|
|
* - ``RTEMS_INVALID_ADDRESS``
|
|
- segment address not in region
|
|
|
|
DESCRIPTION:
|
|
This directive obtains the size in bytes of the specified segment.
|
|
|
|
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.
|
|
|
|
.. raw:: latex
|
|
|
|
\clearpage
|
|
|
|
.. index:: resize segment
|
|
.. index:: rtems_region_resize_segment
|
|
|
|
.. _rtems_region_resize_segment:
|
|
|
|
REGION_RESIZE_SEGMENT - Change size of a segment
|
|
------------------------------------------------
|
|
|
|
CALLING SEQUENCE:
|
|
.. code-block:: c
|
|
|
|
rtems_status_code rtems_region_resize_segment(
|
|
rtems_id id,
|
|
void *segment,
|
|
uintptr_t new_size,
|
|
uintptr_t *old_size
|
|
);
|
|
|
|
DIRECTIVE STATUS CODES:
|
|
.. list-table::
|
|
:class: rtems-table
|
|
|
|
* - ``RTEMS_SUCCESSFUL``
|
|
- segment obtained successfully
|
|
* - ``RTEMS_INVALID_ADDRESS``
|
|
- ``segment`` is NULL
|
|
* - ``RTEMS_INVALID_ADDRESS``
|
|
- ``old_size`` is NULL
|
|
* - ``RTEMS_INVALID_ID``
|
|
- invalid region id
|
|
* - ``RTEMS_INVALID_ADDRESS``
|
|
- segment address not in region
|
|
* - ``RTEMS_UNSATISFIED``
|
|
- unable to make segment larger
|
|
|
|
DESCRIPTION:
|
|
This directive is used to increase or decrease the size of 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.
|
|
|
|
NOTES:
|
|
This directive will obtain the allocator mutex and may cause the calling
|
|
task to be preempted.
|
|
|
|
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.
|
|
|
|
.. raw:: latex
|
|
|
|
\clearpage
|
|
|
|
.. index:: obtain region information
|
|
.. index:: rtems_region_get_information
|
|
|
|
.. _rtems_region_get_information:
|
|
|
|
REGION_GET_INFORMATION - Get region information
|
|
-----------------------------------------------
|
|
|
|
CALLING SEQUENCE:
|
|
.. code-block:: c
|
|
|
|
rtems_status_code rtems_region_get_information(
|
|
rtems_id id,
|
|
Heap_Information_block *the_info
|
|
);
|
|
|
|
DIRECTIVE STATUS CODES:
|
|
.. list-table::
|
|
:class: rtems-table
|
|
|
|
* - ``RTEMS_SUCCESSFUL``
|
|
- information obtained successfully
|
|
* - ``RTEMS_INVALID_ADDRESS``
|
|
- ``the_info`` is NULL
|
|
* - ``RTEMS_INVALID_ID``
|
|
- invalid region id
|
|
|
|
DESCRIPTION:
|
|
This directive is used to obtain information about the used and free memory
|
|
in the region specified by ``id``. This is a snapshot at the time
|
|
of the call. The information will be returned in the structure pointed to
|
|
by ``the_info``.
|
|
|
|
NOTES:
|
|
This directive will obtain the allocator mutex and may cause the calling
|
|
task to be preempted.
|
|
|
|
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.
|
|
|
|
.. raw:: latex
|
|
|
|
\clearpage
|
|
|
|
.. index:: obtain region information on free blocks
|
|
.. index:: rtems_region_get_free_information
|
|
|
|
.. _rtems_region_get_free_information:
|
|
|
|
REGION_GET_FREE_INFORMATION - Get region free information
|
|
---------------------------------------------------------
|
|
|
|
CALLING SEQUENCE:
|
|
.. code-block:: c
|
|
|
|
rtems_status_code rtems_region_get_free_information(
|
|
rtems_id id,
|
|
Heap_Information_block *the_info
|
|
);
|
|
|
|
DIRECTIVE STATUS CODES:
|
|
.. list-table::
|
|
:class: rtems-table
|
|
|
|
* - ``RTEMS_SUCCESSFUL``
|
|
- information obtained successfully
|
|
* - ``RTEMS_INVALID_ADDRESS``
|
|
- ``the_info`` is NULL
|
|
* - ``RTEMS_INVALID_ID``
|
|
- invalid region id
|
|
|
|
DESCRIPTION:
|
|
This directive is used to obtain information about the free memory
|
|
in the region specified by ``id``. This is a snapshot at the time
|
|
of the call. The information will be returned in the structure pointed to
|
|
by ``the_info``.
|
|
|
|
NOTES:
|
|
This directive will obtain the allocator mutex and may cause the calling
|
|
task to be preempted.
|
|
|
|
This uses the same structure to return information as the
|
|
``rtems_region_get_information`` 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 ``rtems_region_get_information``.
|