summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorSebastian Huber <sebastian.huber@embedded-brains.de>2020-06-24 07:10:06 +0200
committerSebastian Huber <sebastian.huber@embedded-brains.de>2021-04-28 07:38:50 +0200
commitb3d3186dc7c1315b48b71328cd174cd81f832420 (patch)
treea926599ce7c8e9e8046c009b539c02bacc6ef903
parent0b9e307f24a28c68acc90b874198a125b1207ab6 (diff)
downloadrtems-b3d3186dc7c1315b48b71328cd174cd81f832420.tar.bz2
rtems: Generate <rtems/rtems/region.h>
Change license to BSD-2-Clause according to file histories and documentation re-licensing agreement. Update #3899. Update #3993.
-rw-r--r--cpukit/include/rtems/rtems/region.h813
1 files changed, 633 insertions, 180 deletions
diff --git a/cpukit/include/rtems/rtems/region.h b/cpukit/include/rtems/rtems/region.h
index 65866ced7b..d4921eec88 100644
--- a/cpukit/include/rtems/rtems/region.h
+++ b/cpukit/include/rtems/rtems/region.h
@@ -1,22 +1,60 @@
+/* SPDX-License-Identifier: BSD-2-Clause */
+
/**
* @file
*
- * @ingroup ClassicRegion
- *
- * @brief Classic Region Manager API
+ * @brief This header file defines the Region Manager API.
+ */
+
+/*
+ * Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de)
+ * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 1. Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ * notice, this list of conditions and the following disclaimer in the
+ * documentation and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
*/
-/* COPYRIGHT (c) 1989-2013.
- * 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:
*
- * The license and distribution terms for this file may be
- * found in the file LICENSE in this distribution or at
- * http://www.rtems.org/license/LICENSE.
+ * https://docs.rtems.org
*/
+/* Generated from spec:/rtems/region/if/header */
+
#ifndef _RTEMS_RTEMS_REGION_H
#define _RTEMS_RTEMS_REGION_H
+#include <stdint.h>
#include <rtems/rtems/attr.h>
#include <rtems/rtems/options.h>
#include <rtems/rtems/status.h>
@@ -27,244 +65,659 @@
extern "C" {
#endif
+/* Generated from spec:/rtems/region/if/group */
+
/**
- * @defgroup ClassicRegion Regions
+ * @defgroup RTEMSAPIClassicRegion Region Manager
*
- * @ingroup RTEMSAPIClassic
+ * @ingroup RTEMSAPIClassic
*
- * This encapsulates functionality related to the Classic API Region
- * Manager.
+ * @brief The Region Manager provides facilities to dynamically allocate memory
+ * in variable sized units.
*/
-/**@{*/
+
+/* Generated from spec:/rtems/region/if/get-segment-size */
/**
- * @brief rtems_region_create
+ * @ingroup RTEMSAPIClassicRegion
+ *
+ * @brief Gets the size of the region segment.
+ *
+ * @param id is the region identifier.
+ *
+ * @param segment is the begin address of the segment.
*
- * Region Manager
+ * @param[out] size 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.
*
- * This routine implements the rtems_region_create directive. The
- * region will have the name name. The memory area managed by
- * the region is of length bytes and starts at starting_address.
- * The memory area will be divided into as many allocatable units of
- * page_size bytes as possible. The attribute_set determines which
- * thread queue discipline is used by the region. It returns the
- * id of the created region in ID.
+ * This directive obtains the size in bytes of the segment specified by
+ * ``segment`` of the region specified by ``id`` in ``size``.
+ *
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
+ *
+ * @retval ::RTEMS_INVALID_ADDRESS The ``segment`` parameter was NULL.
+ *
+ * @retval ::RTEMS_INVALID_ADDRESS The ``size`` parameter was NULL.
+ *
+ * @retval ::RTEMS_INVALID_ID There was no region associated with the
+ * identifier specified by ``id``.
+ *
+ * @retval ::RTEMS_INVALID_ADDRESS The segment was not within the region.
+ *
+ * @par 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.
+ *
+ * @par Constraints
+ * @parblock
+ * 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.
+ * @endparblock
*/
-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
+rtems_status_code rtems_region_get_segment_size(
+ rtems_id id,
+ void *segment,
+ uintptr_t *size
);
+/* Generated from spec:/rtems/region/if/create */
+
/**
- * @brief RTEMS Extend Region
+ * @ingroup RTEMSAPIClassicRegion
+ *
+ * @brief Creates a region.
+ *
+ * @param name is the object name of the region.
+ *
+ * @param starting_address is the starting address of the memory area managed
+ * by the region.
+ *
+ * @param length is the length in bytes of the memory area managed by the
+ * region.
+ *
+ * @param page_size is the alignment of the starting address and length of each
+ * allocated segment of the region.
+ *
+ * @param attribute_set is the attribute set of the region.
+ *
+ * @param[out] id 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.
+ *
+ * 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 #RTEMS_DEFAULT_ATTRIBUTES constant.
+ *
+ * The **task wait queue discipline** is selected by the mutually exclusive
+ * #RTEMS_FIFO and #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 #RTEMS_FIFO attribute.
+ *
+ * * The **priority discipline** is selected by the #RTEMS_PRIORITY attribute.
+ *
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
+ *
+ * @retval ::RTEMS_INVALID_NAME The ``name`` parameter was invalid.
+ *
+ * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL.
+ *
+ * @retval ::RTEMS_INVALID_ADDRESS The ``starting_address`` parameter was NULL.
+ *
+ * @retval ::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 #CONFIGURE_MAXIMUM_REGIONS application configuration option.
+ *
+ * @retval ::RTEMS_INVALID_SIZE The ``page_size`` parameter was invalid.
+ *
+ * @retval ::RTEMS_INVALID_SIZE The memory area specified in
+ * ``starting_address`` and ``length`` was too small.
+ *
+ * @par Notes
+ * For control and maintenance of the region, RTEMS allocates a RNCB from the
+ * local RNCB free pool and initializes it.
+ *
+ * @par Constraints
+ * @parblock
+ * The following constraints apply to this directive:
*
- * This routine implements the rtems_region_extend directive. The
- * region will have the name name. The memory area managed by
- * the region will be attempted to be grown by length bytes using
- * the memory starting at starting_address.
+ * * The directive may be called from within device driver initialization
+ * context.
*
- * @param[in] id is the id of region to grow
- * @param[in] starting_address starting address of memory area for extension
- * @param[in] length is the physical length in bytes to grow the region
+ * * The directive may be called from within task context.
*
- * @retval This method returns RTEMS_SUCCESSFUL if there was not an
- * error. Otherwise, a status code is returned indicating the
- * source of the error.
+ * * 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 #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.
+ * @endparblock
*/
-rtems_status_code rtems_region_extend(
- rtems_id id,
- void *starting_address,
- uintptr_t length
+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
);
+/* Generated from spec:/rtems/region/if/ident */
+
/**
- * @brief RTEMS Region Name to Id
+ * @ingroup RTEMSAPIClassicRegion
+ *
+ * @brief Identifies a region by the object name.
+ *
+ * @param name is the object name to look up.
+ *
+ * @param[out] id 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.
+ *
+ * This directive obtains a region identifier associated with the region name
+ * specified in ``name``.
+ *
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
+ *
+ * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL.
+ *
+ * @retval ::RTEMS_INVALID_NAME The ``name`` parameter was 0.
*
- * This routine implements the rtems_region_ident directive.
- * This directive returns the region ID associated with name.
- * If more than one region is named name, then the region
- * to which the ID belongs is arbitrary.
+ * @retval ::RTEMS_INVALID_NAME There was no object with the specified name on
+ * the local node.
*
- * @param[in] name is the user defined region name
- * @param[in] id is the pointer to region id
+ * @par Notes
+ * @parblock
+ * 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.
*
- * @retval This method returns RTEMS_SUCCESSFUL if there was not an
- * error. Otherwise, a status code is returned indicating the
- * source of the error. If successful, the id will
- * be filled in with the region id.
+ * 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.
+ * @endparblock
+ *
+ * @par Constraints
+ * @parblock
+ * 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.
+ * @endparblock
*/
-rtems_status_code rtems_region_ident(
- rtems_name name,
- rtems_id *id
-);
+rtems_status_code rtems_region_ident( rtems_name name, rtems_id *id );
+
+/* Generated from spec:/rtems/region/if/delete */
/**
- * @brief RTEMS Get Region Information
+ * @ingroup RTEMSAPIClassicRegion
+ *
+ * @brief Deletes the region.
+ *
+ * @param id is the region identifier.
+ *
+ * This directive deletes the region specified by ``id``.
+ *
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
+ *
+ * @retval ::RTEMS_INVALID_ID There was no region associated with the
+ * identifier specified by ``id``.
+ *
+ * @retval ::RTEMS_RESOURCE_IN_USE There were segments of the region still in
+ * use.
*
- * This routine implements the rtems_region_get_information directive.
- * This directive returns information about the heap associated with
- * this region.
+ * @par Notes
+ * @parblock
+ * The region cannot be deleted if any of its segments are still allocated.
*
- * @param[in] id is the region id
- * @param[in] the_info is the pointer to region information block
+ * The RNCB for the deleted region is reclaimed by RTEMS.
+ * @endparblock
*
- * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful and
- * *id filled with the region information block
+ * @par Constraints
+ * @parblock
+ * 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.
+ * @endparblock
*/
-rtems_status_code rtems_region_get_information(
- rtems_id id,
- Heap_Information_block *the_info
-);
+rtems_status_code rtems_region_delete( rtems_id id );
+
+/* Generated from spec:/rtems/region/if/extend */
/**
- * @brief RTEMS Get Region Free Information
+ * @ingroup RTEMSAPIClassicRegion
+ *
+ * @brief Extends the region.
+ *
+ * @param id is the region identifier.
*
- * This routine implements the rtems_region_get_free_information directive.
- * This directive returns information about the free blocks in the
- * heap associated with this region. Information about the used blocks
- * will be returned as zero.
+ * @param starting_address is the starting address of the memory area to extend
+ * the region.
*
- * @param[in] id is the region id
- * @param[in] the_info is the pointer to region information block
+ * @param length is the length in bytes of the memory area to extend the
+ * region.
*
- * @retval This method returns RTEMS_SUCCESSFUL if there was not an
- * error. Otherwise, a status code is returned indicating the
- * source of the error. If successful, the the_info will
- * be filled in with the region information block.
+ * This directive adds the memory area which starts at ``starting_address`` for
+ * ``length`` bytes to the region specified by ``id``.
+ *
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
+ *
+ * @retval ::RTEMS_INVALID_ADDRESS The ``starting_address`` parameter was NULL.
+ *
+ * @retval ::RTEMS_INVALID_ID There was no region associated with the
+ * identifier specified by ``id``.
+ *
+ * @retval ::RTEMS_INVALID_ADDRESS The memory area specified by
+ * ``starting_address`` and ``length`` was insufficient to extend the heap.
+ *
+ * @par 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.
+ *
+ * @par Constraints
+ * @parblock
+ * 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.
+ * @endparblock
*/
-rtems_status_code rtems_region_get_free_information(
- rtems_id id,
- Heap_Information_block *the_info
+rtems_status_code rtems_region_extend(
+ rtems_id id,
+ void *starting_address,
+ uintptr_t length
);
+/* Generated from spec:/rtems/region/if/get-segment */
+
/**
- * @brief RTEMS Delete Region
+ * @ingroup RTEMSAPIClassicRegion
+ *
+ * @brief Gets a segment from the region.
+ *
+ * @param id is the region identifier.
+ *
+ * @param size is the size in bytes of the segment to allocate.
+ *
+ * @param option_set is the option set.
+ *
+ * @param timeout is the timeout in clock ticks if the #RTEMS_WAIT option is
+ * set. Use #RTEMS_NO_TIMEOUT to wait potentially forever.
+ *
+ * @param segment 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.
+ *
+ * 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 #RTEMS_DEFAULT_OPTIONS
+ * constant.
+ *
+ * The calling task can **wait** or **try to get** a segment from the region
+ * according to the mutually exclusive #RTEMS_WAIT and #RTEMS_NO_WAIT options.
+ *
+ * * **Waiting to get** a segment from the region is the default and can be
+ * emphasized through the use of the #RTEMS_WAIT option. The ``timeout``
+ * parameter defines how long the calling task is willing to wait. Use
+ * #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
+ * #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 ::RTEMS_UNSATISFIED status is returned.
+ *
+ * With either #RTEMS_WAIT or #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 ::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 ::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 #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
+ * #RTEMS_FIFO option specified, then the calling task is placed at the rear of
+ * the wait queue.
+ *
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
+ *
+ * @retval ::RTEMS_INVALID_ADDRESS The ``segment`` parameter was NULL.
+ *
+ * @retval ::RTEMS_INVALID_SIZE The ``size`` parameter was zero.
+ *
+ * @retval ::RTEMS_INVALID_ID There was no region associated with the
+ * identifier specified by ``id``.
+ *
+ * @retval ::RTEMS_INVALID_SIZE The ``size`` parameter exceeded the maximum
+ * segment size which is possible for the region.
+ *
+ * @retval ::RTEMS_UNSATISFIED The region had no segment of the requested size
+ * immediately available.
+ *
+ * @retval ::RTEMS_TIMEOUT The timeout happened while the calling task was
+ * waiting to get a segment from the region.
+ *
+ * @par 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.
+ *
+ * @par Constraints
+ * @parblock
+ * The following constraints apply to this directive:
*
- * This routine implements the rtems_region_delete directive. The
- * region indicated by ID is deleted, provided that none of its segments are
- * still allocated.
+ * * The directive may be called from within device driver initialization
+ * context.
*
- * @param[in] id is the region id
+ * * The directive may be called from within task context.
*
- * @retval This method returns RTEMS_SUCCESSFUL if there was not an
- * error. Otherwise, a status code is returned indicating the
- * source of the error.
+ * * 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 #RTEMS_WAIT
+ * option is set, the calling task blocks at some point during the directive
+ * call.
+ *
+ * * The timeout functionality of the directive requires a clock tick.
+ * @endparblock
*/
-rtems_status_code rtems_region_delete(
- rtems_id id
+rtems_status_code rtems_region_get_segment(
+ rtems_id id,
+ uintptr_t size,
+ rtems_option option_set,
+ rtems_interval timeout,
+ void **segment
);
+/* Generated from spec:/rtems/region/if/return-segment */
+
/**
- * @brief RTEMS Get Region Segment
- *
- * This routine implements the rtems_region_get_segment directive. It
- * attempts to allocate a segment from the region associated with @a id.
- * If a segment of the requested @a size size can be allocated, its address
- * is returned in @a segment. If no segment is available, then the task
- * may return immediately or block waiting for a segment with an optional
- * timeout of @a timeout clock ticks. Whether the task blocks or returns
- * immediately is based on the no_wait option in the @a option_set.
- *
- * @param[in] id is the region id
- * @param[in] size is the segment size in bytes
- * @param[in] option_set is the wait option
- * @param[in] timeout is the number of ticks to wait (0 means wait forever)
- * @param[in] segment is the pointer to segment address
- *
- * @retval This method returns RTEMS_SUCCESSFUL if there was not an
- * error. Otherwise, a status code is returned indicating the
- * source of the error. If successful, the segment will
- * be filled in with the segment address.
+ * @ingroup RTEMSAPIClassicRegion
+ *
+ * @brief Returns the segment to the region.
+ *
+ * @param id is the region identifier.
+ *
+ * @param segment is the begin address of the segment to return.
+ *
+ * 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.
+ *
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
+ *
+ * @retval ::RTEMS_INVALID_ID There was no region associated with the
+ * identifier specified by ``id``.
+ *
+ * @retval ::RTEMS_INVALID_ADDRESS The segment was not within the region.
+ *
+ * @par Notes
+ * @parblock
+ * 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.
+ * @endparblock
+ *
+ * @par Constraints
+ * @parblock
+ * 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.
+ * @endparblock
*/
-rtems_status_code rtems_region_get_segment(
- rtems_id id,
- uintptr_t size,
- rtems_option option_set,
- rtems_interval timeout,
- void **segment
-);
+rtems_status_code rtems_region_return_segment( rtems_id id, void *segment );
+
+/* Generated from spec:/rtems/region/if/resize-segment */
/**
- * @brief RTEMS Get Region Segment Size
+ * @ingroup RTEMSAPIClassicRegion
+ *
+ * @brief Changes the size of the segment.
+ *
+ * @param id is the region identifier.
*
- * This routine implements the rtems_region_get_segment_size directive. It
- * returns the size in bytes of the specified user memory area.
+ * @param segment is the begin address of the segment to resize.
*
- * @param[in] id is the region id
- * @param[in] segment is the segment address
- * @param[in] size is the pointer to segment size in bytes
+ * @param size is the requested new size of the segment.
*
- * @retval This method returns RTEMS_SUCCESSFUL if there was not an
- * error. Otherwise, a status code is returned indicating the
- * source of the error. If successful, the size will
- * be filled in with the segment size in bytes.
+ * @param[out] old_size 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.
+ *
+ * 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.
+ *
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
+ *
+ * @retval ::RTEMS_INVALID_ADDRESS The ``old_size`` parameter was NULL.
+ *
+ * @retval ::RTEMS_INVALID_ID There was no region associated with the
+ * identifier specified by ``id``.
+ *
+ * @retval ::RTEMS_INVALID_ADDRESS The segment was not within the region.
+ *
+ * @retval ::RTEMS_UNSATISFIED The region was unable to resize the segment.
+ *
+ * @par 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.
+ *
+ * @par Constraints
+ * @parblock
+ * 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.
+ * @endparblock
*/
-rtems_status_code rtems_region_get_segment_size(
- rtems_id id,
- void *segment,
- uintptr_t *size
+rtems_status_code rtems_region_resize_segment(
+ rtems_id id,
+ void *segment,
+ uintptr_t size,
+ uintptr_t *old_size
);
+/* Generated from spec:/rtems/region/if/get-information */
+
/**
- * @brief RTEMS Return Region Segment
+ * @ingroup RTEMSAPIClassicRegion
+ *
+ * @brief Gets the region information.
+ *
+ * @param id is the region identifier.
+ *
+ * @param[out] the_info 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.
+ *
+ * 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``.
+ *
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
+ *
+ * @retval ::RTEMS_INVALID_ADDRESS The ``the_info`` parameter was NULL.
+ *
+ * @retval ::RTEMS_INVALID_ID There was no region associated with the
+ * identifier specified by ``id``.
+ *
+ * @par Notes
+ * @parblock
+ * 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
+ * rtems_region_get_free_information().
+ * @endparblock
+ *
+ * @par Constraints
+ * @parblock
+ * The following constraints apply to this directive:
*
- * This routine implements the rtems_region_return_segment directive. It
- * frees the segment to the region associated with ID. The segment must
- * have been previously allocated from the same region. If freeing the
- * segment results in enough memory being available to satisfy the
- * rtems_region_get_segment of the first blocked task, then that task and as
- * many subsequent tasks as possible will be unblocked with their requests
- * satisfied.
+ * * The directive may be called from within device driver initialization
+ * context.
*
- * @param[in] id is the region id
- * @param[in] segment is the pointer to segment address
+ * * The directive may be called from within task context.
*
- * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful
+ * * The directive may obtain and release the object allocator mutex. This may
+ * cause the calling task to be preempted.
+ * @endparblock
*/
-rtems_status_code rtems_region_return_segment(
- rtems_id id,
- void *segment
+rtems_status_code rtems_region_get_information(
+ rtems_id id,
+ Heap_Information_block *the_info
);
+/* Generated from spec:/rtems/region/if/get-free-information */
+
/**
- * @brief Resize RTEMS Region Segment
- *
- * This routine implements the rtems_region_resize_segment directive. It
- * tries to resize segment in the region associated with 'id' to the new size
- * 'size' in place. The first 'size' or old size bytes of the segment
- * (whatever is less) are guaranteed to remain unmodified. The segment must
- * have been previously allocated from the same region. If resizing the
- * segment results in enough memory being available to satisfy the
- * rtems_region_get_segment of the first blocked task, then that task and as
- * many subsequent tasks as possible will be unblocked with their requests
- * satisfied.
- *
- * @param[in] id is the region id
- * @param[in] segment is the pointer to segment address
- * @param[in] size is the new required size
- * @retval RTEMS_SUCCESSFUL if operation successful, RTEMS_UNSATISFIED if the
- * the segment can't be resized in place or any other code at failure
- *
- * @note On RTEMS_SUCCESSFUL or RTEMS_UNSATISFIED exit it returns into the
- * 'old_size' the old size in bytes of the user memory area of the
- * specified segment.
+ * @ingroup RTEMSAPIClassicRegion
+ *
+ * @brief Gets the region free information.
+ *
+ * @param id is the region identifier.
+ *
+ * @param[out] the_info 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 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``.
+ *
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
+ *
+ * @retval ::RTEMS_INVALID_ADDRESS The ``the_info`` parameter was NULL.
+ *
+ * @retval ::RTEMS_INVALID_ID There was no region associated with the
+ * identifier specified by ``id``.
+ *
+ * @par Notes
+ * @parblock
+ * This directive 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().
+ * @endparblock
+ *
+ * @par Constraints
+ * @parblock
+ * 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.
+ * @endparblock
*/
-rtems_status_code rtems_region_resize_segment(
- rtems_id id,
- void *segment,
- uintptr_t size,
- uintptr_t *old_size
+rtems_status_code rtems_region_get_free_information(
+ rtems_id id,
+ Heap_Information_block *the_info
);
-/**@}*/
-
#ifdef __cplusplus
}
#endif
-#endif
-/* end of include file */
+#endif /* _RTEMS_RTEMS_REGION_H */