From b3d3186dc7c1315b48b71328cd174cd81f832420 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Wed, 24 Jun 2020 07:10:06 +0200 Subject: rtems: Generate Change license to BSD-2-Clause according to file histories and documentation re-licensing agreement. Update #3899. Update #3993. --- cpukit/include/rtems/rtems/region.h | 813 ++++++++++++++++++++++++++++-------- 1 file 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 #include #include #include @@ -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 */ -- cgit v1.2.3