diff --git a/c-user/region/directives.rst b/c-user/region/directives.rst index be994f6..86bb537 100644 --- a/c-user/region/directives.rst +++ b/c-user/region/directives.rst @@ -1,561 +1,916 @@ .. 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() +--------------------- -CALLING SEQUENCE: - .. code-block:: c +Creates a region. - 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:: CALLING SEQUENCE: -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +.. code-block:: c - * - ``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 + 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 + ); -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. +.. rubric:: PARAMETERS: - 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. +``name`` + This parameter is the object name of 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. +``starting_address`` + This parameter is the starting address of the memory area managed by 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. +``length`` + This parameter is the length in bytes of the memory area managed by the + region. -NOTES: - This directive will obtain the allocator mutex and may cause the calling - task to be preempted. +``page_size`` + This parameter is the alignment of the starting address and length of each + allocated segment of the region. - The following region attribute constants are defined by RTEMS: +``attribute_set`` + This parameter is the attribute set of the region. - .. list-table:: - :class: rtems-table +``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. - * - ``RTEMS_FIFO`` - - tasks wait by FIFO (default) - * - ``RTEMS_PRIORITY`` - - tasks wait by priority +.. 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 + `_. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``starting_address`` parameter was `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. + +.. 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:: get ID of a region -.. index:: obtain ID of a region -.. index:: rtems_region_ident +.. index:: rtems_region_ident() -.. _rtems_region_ident: +.. _InterfaceRtemsRegionIdent: -REGION_IDENT - Get ID of a region ---------------------------------- +rtems_region_ident() +-------------------- -CALLING SEQUENCE: - .. code-block:: c +Identifies a region by the object name. - rtems_status_code rtems_region_ident( - rtems_name name, - rtems_id *id - ); +.. rubric:: CALLING SEQUENCE: -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +.. code-block:: c - * - ``RTEMS_SUCCESSFUL`` - - region identified successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``id`` is NULL - * - ``RTEMS_INVALID_NAME`` - - region name not found + rtems_status_code rtems_region_ident( rtems_name name, rtems_id *id ); -DESCRIPTION: +.. rubric:: PARAMETERS: - 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. +``name`` + This parameter is the object name to look up. -NOTES: - This directive will not cause the running task to be preempted. +``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. + +.. rubric:: DESCRIPTION: + +This directive obtains a region identifier associated with the region name +specified in ``name``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``id`` parameter was `NULL + `_. + +: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() +--------------------- -CALLING SEQUENCE: - .. code-block:: c +Deletes the region. - rtems_status_code rtems_region_delete( - rtems_id id - ); +.. rubric:: CALLING SEQUENCE: -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +.. code-block:: c - * - ``RTEMS_SUCCESSFUL`` - - region deleted successfully - * - ``RTEMS_INVALID_ID`` - - invalid region id - * - ``RTEMS_RESOURCE_IN_USE`` - - segments still in use + rtems_status_code rtems_region_delete( rtems_id 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:: PARAMETERS: -NOTES: - This directive will obtain the allocator mutex and may cause the calling - task to be preempted. +``id`` + This parameter is the region identifier. - 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. +.. rubric:: DESCRIPTION: + +This directive deletes the region specified by ``id``. + +.. rubric:: RETURN VALUES: + +: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_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: +.. _InterfaceRtemsRegionExtend: -REGION_EXTEND - Add memory to a region --------------------------------------- +rtems_region_extend() +--------------------- -CALLING SEQUENCE: - .. code-block:: c +Extends the region. - rtems_status_code rtems_region_extend( - rtems_id id, - void *starting_address, - uintptr_t length - ); +.. rubric:: CALLING SEQUENCE: -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +.. code-block:: c - * - ``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 + rtems_status_code rtems_region_extend( + rtems_id id, + void *starting_address, + uintptr_t length + ); -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`. +.. rubric:: PARAMETERS: - 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. +``id`` + This parameter is the region identifier. -NOTES: - This directive will obtain the allocator mutex and may cause the calling - task to be preempted. +``starting_address`` + This parameter is the starting address of the memory area to extend the + region. - 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. +``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 + `_. + +: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: +.. _InterfaceRtemsRegionGetSegment: -REGION_GET_SEGMENT - Get segment from a region ----------------------------------------------- +rtems_region_get_segment() +-------------------------- -CALLING SEQUENCE: - .. code-block:: c +Gets a segment from the region. - rtems_status_code rtems_region_get_segment( - rtems_id id, - uintptr_t size, - rtems_option option_set, - rtems_interval timeout, - void **segment - ); +.. rubric:: CALLING SEQUENCE: -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +.. code-block:: c - * - ``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 + rtems_status_code rtems_region_get_segment( + rtems_id id, + uintptr_t size, + rtems_option option_set, + rtems_interval timeout, + void **segment + ); -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. +.. rubric:: PARAMETERS: - 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. +``id`` + This parameter is the region identifier. - 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. +``size`` + This parameter is the size in bytes of the segment to allocate. -NOTES: - This directive will obtain the allocator mutex and may cause the calling - task to be preempted. +``option_set`` + This parameter is the option set. - 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. +``timeout`` + This parameter is the timeout in :term:`clock ticks ` if the + :c:macro:`RTEMS_WAIT` option is set. Use :c:macro:`RTEMS_NO_TIMEOUT` to + wait potentially forever. - The following segment acquisition option constants are defined by RTEMS: +``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. - .. list-table:: - :class: rtems-table +.. rubric:: DESCRIPTION: - * - ``RTEMS_WAIT`` - - task will wait for segment (default) - * - ``RTEMS_NO_WAIT`` - - task should not wait +This directive gets a segment from the region specified by ``id``. - A clock tick is required to support the timeout functionality of this - directive. +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 + `_. + +: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: + +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:: RETURN VALUES: + +: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. + +* The size of the segment required by the waiting task is less than or equal to + the size of the segment returned. + +.. 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 unblock a task. This may cause the calling task to be + preempted. + +* 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/resize-segment .. 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 + \clearpage +.. index:: rtems_region_resize_segment() .. index:: resize segment -.. index:: rtems_region_resize_segment -.. _rtems_region_resize_segment: +.. _InterfaceRtemsRegionResizeSegment: -REGION_RESIZE_SEGMENT - Change size of a segment ------------------------------------------------- +rtems_region_resize_segment() +----------------------------- -CALLING SEQUENCE: - .. code-block:: c +Changes the size of the segment. - rtems_status_code rtems_region_resize_segment( - rtems_id id, - void *segment, - uintptr_t new_size, - uintptr_t *old_size - ); +.. rubric:: CALLING SEQUENCE: -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +.. code-block:: c - * - ``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 + rtems_status_code rtems_region_resize_segment( + rtems_id id, + void *segment, + uintptr_t size, + uintptr_t *old_size + ); -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. +.. rubric:: PARAMETERS: -NOTES: - This directive will obtain the allocator mutex and may cause the calling - task to be preempted. +``id`` + This parameter is the region identifier. - 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. +``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 + `_ variable. When the + directive call is successful, the old size of the segment will be stored in + this variable. + +.. rubric:: DESCRIPTION: + +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 + `_. + +: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: -REGION_GET_INFORMATION - Get region information ------------------------------------------------ +rtems_region_get_information() +------------------------------ -CALLING SEQUENCE: - .. code-block:: c +Gets the region information. - rtems_status_code rtems_region_get_information( - rtems_id id, - Heap_Information_block *the_info - ); +.. rubric:: CALLING SEQUENCE: -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +.. code-block:: c - * - ``RTEMS_SUCCESSFUL`` - - information obtained successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``the_info`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid region id + rtems_status_code rtems_region_get_information( + rtems_id id, + Heap_Information_block *the_info + ); -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``. +.. rubric:: PARAMETERS: -NOTES: - This directive will obtain the allocator mutex and may cause the calling - task to be preempted. +``id`` + This parameter is the region identifier. - 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. +``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``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``the_info`` parameter was `NULL + `_. + +:c:macro:`RTEMS_INVALID_ID` + There was no region associated with the identifier specified by ``id``. + +.. rubric:: NOTES: + +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. + +To get only the free information of the region use +:ref:`InterfaceRtemsRegionGetFreeInformation`. + +.. 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: +.. _InterfaceRtemsRegionGetFreeInformation: -REGION_GET_FREE_INFORMATION - Get region free information ---------------------------------------------------------- +rtems_region_get_free_information() +----------------------------------- -CALLING SEQUENCE: - .. code-block:: c +Gets the region free information. - rtems_status_code rtems_region_get_free_information( - rtems_id id, - Heap_Information_block *the_info - ); +.. rubric:: CALLING SEQUENCE: -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +.. code-block:: c - * - ``RTEMS_SUCCESSFUL`` - - information obtained successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``the_info`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid region id + rtems_status_code rtems_region_get_free_information( + rtems_id id, + Heap_Information_block *the_info + ); -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:: PARAMETERS: -NOTES: - This directive will obtain the allocator mutex and may cause the calling - task to be preempted. +``id`` + This parameter is the region identifier. - This uses the same structure to return information as the - ``rtems_region_get_information`` directive but does not fill in the - used information. +``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. - 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``. +.. 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 + `_. + +:c:macro:`RTEMS_INVALID_ID` + There was no region associated with the identifier specified by ``id``. + +.. rubric:: NOTES: + +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 + `_ 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 + `_. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``size`` parameter was `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 -- :ref:`rtems_region_create` +The Region Manager provides facilities to dynamically allocate memory in +variable sized units. The directives provided by the Region Manager are: -- :ref:`rtems_region_ident` +* :ref:`InterfaceRtemsRegionCreate` - Creates a region. -- :ref:`rtems_region_delete` +* :ref:`InterfaceRtemsRegionIdent` - Identifies a region by the object name. -- :ref:`rtems_region_extend` +* :ref:`InterfaceRtemsRegionDelete` - Deletes the region. -- :ref:`rtems_region_get_segment` +* :ref:`InterfaceRtemsRegionExtend` - Extends the region. -- :ref:`rtems_region_return_segment` +* :ref:`InterfaceRtemsRegionGetSegment` - Gets a segment from the region. -- :ref:`rtems_region_get_segment_size` +* :ref:`InterfaceRtemsRegionReturnSegment` - Returns the segment to the region. -- :ref:`rtems_region_resize_segment` +* :ref:`InterfaceRtemsRegionResizeSegment` - Changes the size of the segment. -- :ref:`rtems_region_get_information` +* :ref:`InterfaceRtemsRegionGetInformation` - Gets the region information. -- :ref:`rtems_region_get_free_information` +* :ref:`InterfaceRtemsRegionGetFreeInformation` - Gets the region free + information. + +* :ref:`InterfaceRtemsRegionGetSegmentSize` - Gets the size of the region + segment.