[PATCH] c-user: Generate region manager documentation
Sebastian Huber
sebastian.huber at embedded-brains.de
Tue Apr 27 18:02:40 UTC 2021
The documentation is a consolidation of the comments in Doxygen markup
and the documentation sources in Sphinx markup. The documentation was
transfered to interface specification items. The documentation source
files were generated from the items by a script.
Update #3993.
---
Here is the updated document for review:
https://ftp.rtems.org/pub/rtems/people/sebh/c-user.pdf
c-user/region/directives.rst | 1269 ++++++++++++++++++++------------
c-user/region/introduction.rst | 58 +-
2 files changed, 857 insertions(+), 470 deletions(-)
diff --git a/c-user/region/directives.rst b/c-user/region/directives.rst
index be994f6..3ec06cd 100644
--- a/c-user/region/directives.rst
+++ b/c-user/region/directives.rst
@@ -1,561 +1,914 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
+.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de)
.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+.. This file is part of the RTEMS quality process and was automatically
+.. generated. If you find something that needs to be fixed or
+.. worded better please post a report or patch to an RTEMS mailing list
+.. or raise a bug report:
+..
+.. https://www.rtems.org/bugs.html
+..
+.. For information on updating and regenerating please refer to the How-To
+.. section in the Software Requirements Engineering chapter of the
+.. RTEMS Software Engineering manual. The manual is provided as a part of
+.. a release. For development sources please refer to the online
+.. documentation at:
+..
+.. https://docs.rtems.org
+
+.. _RegionManagerDirectives:
+
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.
+This section details the directives of the Region Manager. A subsection is
+dedicated to each of this manager's directives and lists the calling sequence,
+parameters, description, return values, and notes of the directive.
+
+.. Generated from spec:/rtems/region/if/create
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_region_create()
.. index:: create a region
-.. _rtems_region_create:
+.. _InterfaceRtemsRegionCreate:
-REGION_CREATE - Create a region
--------------------------------
+rtems_region_create()
+---------------------
+
+Creates a region.
+
+.. rubric:: 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
+ );
+
+.. rubric:: PARAMETERS:
+
+``name``
+ This parameter is the object name of the region.
+
+``starting_address``
+ This parameter is the starting address of the memory area managed by the
+ region.
+
+``length``
+ This parameter is the length in bytes of the memory area managed by the
+ region.
+
+``page_size``
+ This parameter is the alignment of the starting address and length of each
+ allocated segment of the region.
+
+``attribute_set``
+ This parameter is the attribute set of the region.
+
+``id``
+ This parameter is the pointer to an object identifier variable. When the
+ directive call is successful, the identifier of the created region will be
+ stored in this variable.
+
+.. rubric:: DESCRIPTION:
+
+This directive creates a region which resides on the local node. The region
+has the user-defined object name specified in ``name``. The assigned object
+identifier is returned in ``id``. This identifier is used to access the region
+with other region related directives.
+
+The region manages the **contiguous memory area** which starts at
+``starting_address`` and is ``length`` 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
+will be an integral multiple of ``page_size``. The specified page size will be
+aligned to an implementation-dependent minimum alignment if necessary.
+
+The **attribute set** specified in ``attribute_set`` is built through a
+*bitwise or* of the attribute constants described below. Not all combinations
+of attributes are allowed. Some attributes are mutually exclusive. If
+mutually exclusive attributes are combined, the behaviour is undefined.
+Attributes not mentioned below are not evaluated by this directive and have no
+effect. Default attributes can be selected by using the
+:c:macro:`RTEMS_DEFAULT_ATTRIBUTES` constant.
+
+The **task wait queue discipline** is selected by the mutually exclusive
+:c:macro:`RTEMS_FIFO` and :c:macro:`RTEMS_PRIORITY` attributes. The discipline
+defines the order in which tasks wait for allocatable segments on a currently
+empty region.
+
+* The **FIFO discipline** is the default and can be emphasized through use of
+ the :c:macro:`RTEMS_FIFO` attribute.
+
+* The **priority discipline** is selected by the :c:macro:`RTEMS_PRIORITY`
+ attribute.
+
+.. rubric:: RETURN VALUES:
+
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
+
+:c:macro:`RTEMS_INVALID_NAME`
+ The ``name`` parameter was invalid.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``id`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``starting_address`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
+
+:c:macro:`RTEMS_TOO_MANY`
+ There was no inactive object available to create a region. The number of
+ regions available to the application is configured through the
+ :ref:`CONFIGURE_MAXIMUM_REGIONS` application configuration option.
+
+:c:macro:`RTEMS_INVALID_SIZE`
+ The ``page_size`` parameter was invalid.
+
+:c:macro:`RTEMS_INVALID_SIZE`
+ The memory area specified in ``starting_address`` and ``length`` was too
+ small.
-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
+.. rubric:: NOTES:
+
+For control and maintenance of the region, RTEMS allocates a :term:`RNCB` from
+the local RNCB free pool and initializes it.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive may obtain and release the object allocator mutex. This may
+ cause the calling task to be preempted.
+
+* The number of regions available to the application is configured through the
+ :ref:`CONFIGURE_MAXIMUM_REGIONS` application configuration option.
+
+* Where the object class corresponding to the directive is configured to use
+ unlimited objects, the directive may allocate memory from the RTEMS
+ Workspace.
+
+.. Generated from spec:/rtems/region/if/ident
.. raw:: latex
- \clearpage
+ \clearpage
+
+.. index:: rtems_region_ident()
+
+.. _InterfaceRtemsRegionIdent:
+
+rtems_region_ident()
+--------------------
+
+Identifies a region by the object name.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
-.. index:: get ID of a region
-.. index:: obtain ID of a region
-.. index:: rtems_region_ident
+ rtems_status_code rtems_region_ident( rtems_name name, rtems_id *id );
-.. _rtems_region_ident:
+.. rubric:: PARAMETERS:
-REGION_IDENT - Get ID of a region
----------------------------------
+``name``
+ This parameter is the object name to look up.
-CALLING SEQUENCE:
- .. code-block:: c
+``id``
+ This parameter is the pointer to an object identifier variable. When the
+ directive call is successful, the object identifier of an object with the
+ specified name will be stored in this variable.
- rtems_status_code rtems_region_ident(
- rtems_name name,
- rtems_id *id
- );
+.. rubric:: DESCRIPTION:
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+This directive obtains a region identifier associated with the region name
+specified in ``name``.
- * - ``RTEMS_SUCCESSFUL``
- - region identified successfully
- * - ``RTEMS_INVALID_ADDRESS``
- - ``id`` is NULL
- * - ``RTEMS_INVALID_NAME``
- - region name not found
+.. rubric:: RETURN VALUES:
-DESCRIPTION:
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
- 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.
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``id`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
-NOTES:
- This directive will not cause the running task to be preempted.
+:c:macro:`RTEMS_INVALID_NAME`
+ The ``name`` parameter was 0.
+
+:c:macro:`RTEMS_INVALID_NAME`
+ There was no object with the specified name on the local node.
+
+.. rubric:: NOTES:
+
+If the region name is not unique, then the region identifier will match the
+first region with that name in the search order. However, this region
+identifier is not guaranteed to correspond to the desired region.
+
+The objects are searched from lowest to the highest index. Only the local node
+is searched.
+
+The region identifier is used with other region related directives to access
+the region.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/region/if/delete
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_region_delete()
.. index:: delete a region
-.. index:: rtems_region_delete
-.. _rtems_region_delete:
+.. _InterfaceRtemsRegionDelete:
-REGION_DELETE - Delete a region
--------------------------------
+rtems_region_delete()
+---------------------
+
+Deletes the region.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_region_delete( rtems_id id );
-CALLING SEQUENCE:
- .. code-block:: c
+.. rubric:: PARAMETERS:
- rtems_status_code rtems_region_delete(
- rtems_id id
- );
+``id``
+ This parameter is the region identifier.
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+.. rubric:: DESCRIPTION:
- * - ``RTEMS_SUCCESSFUL``
- - region deleted successfully
- * - ``RTEMS_INVALID_ID``
- - invalid region id
- * - ``RTEMS_RESOURCE_IN_USE``
- - segments still in use
+This directive deletes the region specified by ``id``.
-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.
+.. rubric:: RETURN VALUES:
-NOTES:
- This directive will obtain the allocator mutex and may cause the calling
- task to be preempted.
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
- 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.
+:c:macro:`RTEMS_INVALID_ID`
+ There was no region associated with the identifier specified by ``id``.
+
+:c:macro:`RTEMS_RESOURCE_IN_USE`
+ There were segments of the region still in use.
+
+.. rubric:: NOTES:
+
+The region cannot be deleted if any of its segments are still allocated.
+
+The :term:`RNCB` for the deleted region is reclaimed by RTEMS.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive may obtain and release the object allocator mutex. This may
+ cause the calling task to be preempted.
+
+* The calling task does not have to be the task that created the object. Any
+ local task that knows the object identifier can delete the object.
+
+* Where the object class corresponding to the directive is configured to use
+ unlimited objects, the directive may free memory to the RTEMS Workspace.
+
+.. Generated from spec:/rtems/region/if/extend
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_region_extend()
.. 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.
+
+.. _InterfaceRtemsRegionExtend:
+
+rtems_region_extend()
+---------------------
+
+Extends the region.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_region_extend(
+ rtems_id id,
+ void *starting_address,
+ uintptr_t length
+ );
+
+.. rubric:: PARAMETERS:
+
+``id``
+ This parameter is the region identifier.
+
+``starting_address``
+ This parameter is the starting address of the memory area to extend the
+ region.
+
+``length``
+ This parameter is the length in bytes of the memory area to extend the
+ region.
+
+.. rubric:: DESCRIPTION:
+
+This directive adds the memory area which starts at ``starting_address`` for
+``length`` bytes to the region specified by ``id``.
+
+.. rubric:: RETURN VALUES:
+
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``starting_address`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
+
+:c:macro:`RTEMS_INVALID_ID`
+ There was no region associated with the identifier specified by ``id``.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The memory area specified by ``starting_address`` and ``length`` was
+ insufficient to extend the heap.
+
+.. rubric:: 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.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive may obtain and release the object allocator mutex. This may
+ cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/region/if/get-segment
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_region_get_segment()
.. 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.
+
+.. _InterfaceRtemsRegionGetSegment:
+
+rtems_region_get_segment()
+--------------------------
+
+Gets a segment from the region.
+
+.. rubric:: 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
+ );
+
+.. rubric:: PARAMETERS:
+
+``id``
+ This parameter is the region identifier.
+
+``size``
+ This parameter is the size in bytes of the segment to allocate.
+
+``option_set``
+ This parameter is the option set.
+
+``timeout``
+ This parameter is the timeout in :term:`clock ticks <clock tick>` if the
+ :c:macro:`RTEMS_WAIT` option is set. Use :c:macro:`RTEMS_NO_TIMEOUT` to
+ wait potentially forever.
+
+``segment``
+ This parameter 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.
+
+.. rubric:: DESCRIPTION:
+
+This directive gets a segment from the region specified by ``id``.
+
+The **option set** specified in ``option_set`` 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 :c:macro:`RTEMS_DEFAULT_OPTIONS` constant.
+
+The calling task can **wait** or **try to get** a segment from the region
+according to the mutually exclusive :c:macro:`RTEMS_WAIT` and
+:c:macro:`RTEMS_NO_WAIT` options.
+
+* **Waiting to get** a segment from the region is the default and can be
+ emphasized through the use of the :c:macro:`RTEMS_WAIT` option. The
+ ``timeout`` parameter defines how long the calling task is willing to wait.
+ Use :c:macro:`RTEMS_NO_TIMEOUT` to wait potentially forever, otherwise set a
+ timeout interval in clock ticks.
+
+* **Trying to get** a segment from the region is selected by the
+ :c:macro:`RTEMS_NO_WAIT` option. If this option is defined, then the
+ ``timeout`` parameter is ignored. When a segment from the region cannot be
+ immediately allocated, then the :c:macro:`RTEMS_UNSATISFIED` status is
+ returned.
+
+With either :c:macro:`RTEMS_WAIT` or :c:macro:`RTEMS_NO_WAIT` if there is a
+segment of the requested size is available, then it is returned in ``segment``
+and this directive returns immediately with the :c:macro:`RTEMS_SUCCESSFUL`
+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 :c:macro:`RTEMS_UNSATISFIED` 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 :c:macro:`RTEMS_PRIORITY`
+option specified, then the calling task is inserted into the wait queue
+according to its priority. But, if the region was created with the
+:c:macro:`RTEMS_FIFO` option specified, then the calling task is placed at the
+rear of the wait queue.
+
+.. rubric:: RETURN VALUES:
+
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``segment`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
+
+:c:macro:`RTEMS_INVALID_SIZE`
+ The ``size`` parameter was zero.
+
+:c:macro:`RTEMS_INVALID_ID`
+ There was no region associated with the identifier specified by ``id``.
+
+:c:macro:`RTEMS_INVALID_SIZE`
+ The ``size`` parameter exceeded the maximum segment size which is possible
+ for the region.
+
+:c:macro:`RTEMS_UNSATISFIED`
+ The region had no segment of the requested size immediately available.
+
+:c:macro:`RTEMS_TIMEOUT`
+ The timeout happened while the calling task was waiting to get a segment
+ from the region.
+
+.. rubric:: 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.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive may obtain and release the object allocator mutex. This may
+ cause the calling task to be preempted.
+
+* When the request cannot be immediately satisfied and the
+ :c:macro:`RTEMS_WAIT` option is set, the calling task blocks at some point
+ during the directive call.
+
+* The timeout functionality of the directive requires a :term:`clock tick`.
+
+.. Generated from spec:/rtems/region/if/return-segment
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_region_return_segment()
.. index:: return segment to region
-.. index:: rtems_region_return_segment
-.. _rtems_region_return_segment:
+.. _InterfaceRtemsRegionReturnSegment:
-REGION_RETURN_SEGMENT - Return segment to a region
---------------------------------------------------
+rtems_region_return_segment()
+-----------------------------
-CALLING SEQUENCE:
- .. code-block:: c
+Returns the segment to the region.
- rtems_status_code rtems_region_return_segment(
- rtems_id id,
- void *segment
- );
+.. rubric:: CALLING SEQUENCE:
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+.. code-block:: c
- * - ``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
+ rtems_status_code rtems_region_return_segment( rtems_id id, void *segment );
-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.
+.. rubric:: PARAMETERS:
-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:
+``id``
+ This parameter is the region identifier.
- - a waiting task has a higher priority than the calling task
+``segment``
+ This parameter is the begin address of the segment to return.
- - the size of the segment required by the waiting task is less than or
- equal to the size of the segment returned.
+.. rubric:: DESCRIPTION:
-.. raw:: latex
+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.
- \clearpage
+.. rubric:: RETURN VALUES:
-.. index:: get size of segment
-.. index:: rtems_region_get_segment_size
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
+
+:c:macro:`RTEMS_INVALID_ID`
+ There was no region associated with the identifier specified by ``id``.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The segment was not within the region.
+
+.. rubric:: 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.
-.. _rtems_region_get_segment_size:
+* The size of the segment required by the waiting task is less than or equal to
+ the size of the segment returned.
-REGION_GET_SEGMENT_SIZE - Obtain size of a segment
---------------------------------------------------
+.. rubric:: CONSTRAINTS:
-CALLING SEQUENCE:
- .. code-block:: c
+The following constraints apply to this directive:
- rtems_status_code rtems_region_get_segment_size(
- rtems_id id,
- void *segment,
- uintptr_t *size
- );
+* The directive may be called from within device driver initialization context.
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+* The directive may be called from within task context.
- * - ``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
+* The directive may unblock a task. This may cause the calling task to be
+ preempted.
-DESCRIPTION:
- This directive obtains the size in bytes of the specified segment.
+* The directive may obtain and release the object allocator mutex. This may
+ cause the calling task to be preempted.
-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.
+.. Generated from spec:/rtems/region/if/resize-segment
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_region_resize_segment()
.. 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.
+
+.. _InterfaceRtemsRegionResizeSegment:
+
+rtems_region_resize_segment()
+-----------------------------
+
+Changes the size of the segment.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_region_resize_segment(
+ rtems_id id,
+ void *segment,
+ uintptr_t size,
+ uintptr_t *old_size
+ );
+
+.. rubric:: PARAMETERS:
+
+``id``
+ This parameter is the region identifier.
+
+``segment``
+ This parameter is the begin address of the segment to resize.
+
+``size``
+ This parameter is the requested new size of the segment.
+
+``old_size``
+ This parameter is the pointer to an `uintptr_t
+ <https://en.cppreference.com/w/c/types/integer>`_ variable. When the
+ directive call is successful, the old size of the segment will be stored in
+ this variable.
+
+.. rubric:: DESCRIPTION:
+
+null This directive is used to increase or decrease the size of the ``segment``
+of the region specified by ``id``. 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.
+
+.. rubric:: RETURN VALUES:
+
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``old_size`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
+
+:c:macro:`RTEMS_INVALID_ID`
+ There was no region associated with the identifier specified by ``id``.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The segment was not within the region.
+
+:c:macro:`RTEMS_UNSATISFIED`
+ The region was unable to resize the segment.
+
+.. rubric:: 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.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive may obtain and release the object allocator mutex. This may
+ cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/region/if/get-information
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_region_get_information()
.. index:: obtain region information
-.. index:: rtems_region_get_information
-.. _rtems_region_get_information:
+.. _InterfaceRtemsRegionGetInformation:
+
+rtems_region_get_information()
+------------------------------
+
+Gets the region information.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_region_get_information(
+ rtems_id id,
+ Heap_Information_block *the_info
+ );
+
+.. rubric:: PARAMETERS:
+
+``id``
+ This parameter is the region identifier.
+
+``the_info``
+ This parameter is the pointer to a Heap_Information_block variable. When
+ the directive call is successful, the information of the region will be
+ stored in this variable.
+
+.. rubric:: 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``.
-REGION_GET_INFORMATION - Get region information
------------------------------------------------
+.. rubric:: RETURN VALUES:
-CALLING SEQUENCE:
- .. code-block:: c
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
- rtems_status_code rtems_region_get_information(
- rtems_id id,
- Heap_Information_block *the_info
- );
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``the_info`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+:c:macro:`RTEMS_INVALID_ID`
+ There was no region associated with the identifier specified by ``id``.
- * - ``RTEMS_SUCCESSFUL``
- - information obtained successfully
- * - ``RTEMS_INVALID_ADDRESS``
- - ``the_info`` is NULL
- * - ``RTEMS_INVALID_ID``
- - invalid region id
+.. rubric:: NOTES:
-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``.
+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.
-NOTES:
- This directive will obtain the allocator mutex and may cause the calling
- task to be preempted.
+To get only the free information of the region use
+:ref:`InterfaceRtemsRegionGetFreeInformation`.
- 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.
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive may obtain and release the object allocator mutex. This may
+ cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/region/if/get-free-information
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_region_get_free_information()
.. 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``.
+
+.. _InterfaceRtemsRegionGetFreeInformation:
+
+rtems_region_get_free_information()
+-----------------------------------
+
+Gets the region free information.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_region_get_free_information(
+ rtems_id id,
+ Heap_Information_block *the_info
+ );
+
+.. rubric:: PARAMETERS:
+
+``id``
+ This parameter is the region identifier.
+
+``the_info``
+ This parameter is the pointer to a Heap_Information_block variable. When
+ the directive call is successful, the free information of the region will
+ be stored in this variable.
+
+.. rubric:: 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``.
+
+.. rubric:: RETURN VALUES:
+
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``the_info`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
+
+:c:macro:`RTEMS_INVALID_ID`
+ There was no region associated with the identifier specified by ``id``.
+
+.. rubric:: NOTES:
+
+null This directive uses the same structure to return information as the
+:ref:`InterfaceRtemsRegionGetInformation` 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 :ref:`InterfaceRtemsRegionGetInformation`.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive may obtain and release the object allocator mutex. This may
+ cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/region/if/get-segment-size
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: rtems_region_get_segment_size()
+.. index:: get size of segment
+
+.. _InterfaceRtemsRegionGetSegmentSize:
+
+rtems_region_get_segment_size()
+-------------------------------
+
+Gets the size of the region segment.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_region_get_segment_size(
+ rtems_id id,
+ void *segment,
+ uintptr_t *size
+ );
+
+.. rubric:: PARAMETERS:
+
+``id``
+ This parameter is the region identifier.
+
+``segment``
+ This parameter is the begin address of the segment.
+
+``size``
+ This parameter is the pointer to a `uintptr_t
+ <https://en.cppreference.com/w/c/types/integer>`_ variable. When the
+ directive call is successful, the size of the segment in bytes will be
+ stored in this variable.
+
+.. rubric:: DESCRIPTION:
+
+This directive obtains the size in bytes of the segment specified by
+``segment`` of the region specified by ``id`` in ``size``.
+
+.. rubric:: RETURN VALUES:
+
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``segment`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``size`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
+
+:c:macro:`RTEMS_INVALID_ID`
+ There was no region associated with the identifier specified by ``id``.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The segment was not within the region.
+
+.. rubric:: 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.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive may obtain and release the object allocator mutex. This may
+ cause the calling task to be preempted.
diff --git a/c-user/region/introduction.rst b/c-user/region/introduction.rst
index 418e397..8075a84 100644
--- a/c-user/region/introduction.rst
+++ b/c-user/region/introduction.rst
@@ -1,29 +1,63 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
+.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de)
.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+.. This file is part of the RTEMS quality process and was automatically
+.. generated. If you find something that needs to be fixed or
+.. worded better please post a report or patch to an RTEMS mailing list
+.. or raise a bug report:
+..
+.. https://www.rtems.org/bugs.html
+..
+.. For information on updating and regenerating please refer to the How-To
+.. section in the Software Requirements Engineering chapter of the
+.. RTEMS Software Engineering manual. The manual is provided as a part of
+.. a release. For development sources please refer to the online
+.. documentation at:
+..
+.. https://docs.rtems.org
+
+.. Generated from spec:/rtems/region/if/group
+
+.. _RegionManagerIntroduction:
+
Introduction
============
-The region manager provides facilities to dynamically allocate memory in
-variable sized units. The directives provided by the region manager are:
+.. The following list was generated from:
+.. spec:/rtems/region/if/create
+.. spec:/rtems/region/if/ident
+.. spec:/rtems/region/if/delete
+.. spec:/rtems/region/if/extend
+.. spec:/rtems/region/if/get-segment
+.. spec:/rtems/region/if/return-segment
+.. spec:/rtems/region/if/resize-segment
+.. spec:/rtems/region/if/get-information
+.. spec:/rtems/region/if/get-free-information
+.. spec:/rtems/region/if/get-segment-size
+
+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:`InterfaceRtemsRegionCreate` - Creates a region.
-- :ref:`rtems_region_ident`
+* :ref:`InterfaceRtemsRegionIdent` - Identifies a region by the object name.
-- :ref:`rtems_region_delete`
+* :ref:`InterfaceRtemsRegionDelete` - Deletes the region.
-- :ref:`rtems_region_extend`
+* :ref:`InterfaceRtemsRegionExtend` - Extends the region.
-- :ref:`rtems_region_get_segment`
+* :ref:`InterfaceRtemsRegionGetSegment` - Gets a segment from the region.
-- :ref:`rtems_region_return_segment`
+* :ref:`InterfaceRtemsRegionReturnSegment` - Returns the segment to the region.
-- :ref:`rtems_region_get_segment_size`
+* :ref:`InterfaceRtemsRegionResizeSegment` - Changes the size of the segment.
-- :ref:`rtems_region_resize_segment`
+* :ref:`InterfaceRtemsRegionGetInformation` - Gets the region information.
-- :ref:`rtems_region_get_information`
+* :ref:`InterfaceRtemsRegionGetFreeInformation` - Gets the region free
+ information.
-- :ref:`rtems_region_get_free_information`
+* :ref:`InterfaceRtemsRegionGetSegmentSize` - Gets the size of the region
+ segment.
--
2.26.2
More information about the devel
mailing list