/* SPDX-License-Identifier: BSD-2-Clause */ /** * @file * * @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. */ /* * 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/header */ #ifndef _RTEMS_RTEMS_REGION_H #define _RTEMS_RTEMS_REGION_H #include #include #include #include #include #include #ifdef __cplusplus extern "C" { #endif /* Generated from spec:/rtems/region/if/group */ /** * @defgroup RTEMSAPIClassicRegion Region Manager * * @ingroup RTEMSAPIClassic * * @brief The Region Manager provides facilities to dynamically allocate memory * in variable sized units. */ /* Generated from spec:/rtems/region/if/create */ /** * @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: * * * 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 #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_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/delete */ /** * @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. * * @par Notes * @parblock * The region cannot be deleted if any of its segments are still allocated. * * The RNCB for the deleted region is reclaimed by RTEMS. * @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. * * * 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_delete( rtems_id id ); /* Generated from spec:/rtems/region/if/extend */ /** * @ingroup RTEMSAPIClassicRegion * * @brief % * * @param id % * * @param starting_address % * * @param length % */ rtems_status_code rtems_region_extend( rtems_id id, void *starting_address, uintptr_t length ); /* Generated from spec:/rtems/region/if/get-free-information */ /** * @ingroup RTEMSAPIClassicRegion * * @brief % * * @param id % * * @param the_info % */ rtems_status_code rtems_region_get_free_information( rtems_id id, Heap_Information_block *the_info ); /* Generated from spec:/rtems/region/if/get-information */ /** * @ingroup RTEMSAPIClassicRegion * * @brief % * * @param id % * * @param the_info % */ rtems_status_code rtems_region_get_information( rtems_id id, Heap_Information_block *the_info ); /* Generated from spec:/rtems/region/if/get-segment */ /** * @ingroup RTEMSAPIClassicRegion * * @brief % * * @param id % * * @param size % * * @param option_set % * * @param timeout % * * @param segment % */ 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/get-segment-size */ /** * @ingroup RTEMSAPIClassicRegion * * @brief % * * @param id % * * @param segment % * * @param size % */ rtems_status_code rtems_region_get_segment_size( rtems_id id, void *segment, uintptr_t *size ); /* Generated from spec:/rtems/region/if/ident */ /** * @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. * * @retval ::RTEMS_INVALID_NAME There was no object with the specified name on * the local node. * * @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. * * 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 ); /* Generated from spec:/rtems/region/if/resize-segment */ /** * @ingroup RTEMSAPIClassicRegion * * @brief % * * @param id % * * @param segment % * * @param size % * * @param old_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/return-segment */ /** * @ingroup RTEMSAPIClassicRegion * * @brief % * * @param id % * * @param segment % */ rtems_status_code rtems_region_return_segment( rtems_id id, void *segment ); #ifdef __cplusplus } #endif #endif /* _RTEMS_RTEMS_REGION_H */