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.

1 files changed, 317 insertions, 174 deletions

diff --git a/cpukit/include/rtems/rtems/region.h b/cpukit/include/rtems/rtems/region.h
index 65866ced7b..60655d9846 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,349 @@
 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/create */
 
 /**
- *  @brief rtems_region_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.
  *
- *  Region Manager
+ * @retval ::RTEMS_INVALID_NAME The ``name`` parameter was invalid.
  *
- *  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.
+ * @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
+  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 */
+
 /**
- * @brief RTEMS Extend Region
+ * @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.
  *
- * 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 obtain and release the object allocator mutex.  This may
+ *   cause the calling task to be preempted.
  *
- * @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 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.
  *
- * @retval This method returns RTEMS_SUCCESSFUL if there was not an
- *         error. Otherwise, a status code is returned indicating the
- *         source of the error.
+ * * 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_extend(
-  rtems_id            id,
-  void               *starting_address,
-  uintptr_t           length
-);
+rtems_status_code rtems_region_delete( rtems_id id );
+
+/* Generated from spec:/rtems/region/if/extend */
 
 /**
- * @brief RTEMS Region Name to Id
+ * @ingroup RTEMSAPIClassicRegion
  *
- * 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.
+ * @brief %
  *
- * @param[in] name is the user defined region name
- * @param[in] id is the pointer to region id
+ * @param id %
  *
- * @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.
+ * @param starting_address %
+ *
+ * @param length %
  */
-rtems_status_code rtems_region_ident(
-  rtems_name    name,
-  rtems_id     *id
+rtems_status_code rtems_region_extend(
+  rtems_id  id,
+  void     *starting_address,
+  uintptr_t length
 );
 
+/* Generated from spec:/rtems/region/if/get-free-information */
+
 /**
- * @brief RTEMS Get Region Information
+ * @ingroup RTEMSAPIClassicRegion
  *
- * This routine implements the rtems_region_get_information directive.
- * This directive returns information about the heap associated with
- * this region.
+ * @brief %
  *
- * @param[in] id is the region id
- * @param[in] the_info is the pointer to region information block
+ * @param id %
  *
- * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful and
- * *id filled with the region information block
+ * @param the_info %
  */
-rtems_status_code rtems_region_get_information(
+rtems_status_code rtems_region_get_free_information(
   rtems_id                id,
   Heap_Information_block *the_info
 );
 
+/* Generated from spec:/rtems/region/if/get-information */
+
 /**
- * @brief RTEMS Get Region Free Information
+ * @ingroup RTEMSAPIClassicRegion
  *
- * 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.
+ * @brief %
  *
- * @param[in] id is the region id
- * @param[in] the_info is the pointer to region information block
+ * @param id %
  *
- * @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.
+ * @param the_info %
  */
-rtems_status_code rtems_region_get_free_information(
+rtems_status_code rtems_region_get_information(
   rtems_id                id,
   Heap_Information_block *the_info
 );
 
+/* Generated from spec:/rtems/region/if/get-segment */
+
 /**
- * @brief RTEMS Delete Region
+ * @ingroup RTEMSAPIClassicRegion
  *
- * This routine implements the rtems_region_delete directive. The
- * region indicated by ID is deleted, provided that none of its segments are
- * still allocated.
+ * @brief %
  *
- * @param[in] id is the region id
+ * @param id %
  *
- * @retval This method returns RTEMS_SUCCESSFUL if there was not an
- *         error. Otherwise, a status code is returned indicating the
- *         source of the error.
- */
-rtems_status_code rtems_region_delete(
-  rtems_id   id
-);
-
-/**
- * @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.
+ * @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
+  rtems_id       id,
+  uintptr_t      size,
+  rtems_option   option_set,
+  rtems_interval timeout,
+  void         **segment
 );
 
+/* Generated from spec:/rtems/region/if/get-segment-size */
+
 /**
- * @brief RTEMS Get Region Segment Size
+ * @ingroup RTEMSAPIClassicRegion
+ *
+ * @brief %
  *
- * This routine implements the rtems_region_get_segment_size directive. It
- * returns the size in bytes of the specified user memory area.
+ * @param id %
  *
- * @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 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 size %
  */
 rtems_status_code rtems_region_get_segment_size(
-  rtems_id           id,
-  void              *segment,
-  uintptr_t         *size
+  rtems_id   id,
+  void      *segment,
+  uintptr_t *size
 );
 
+/* Generated from spec:/rtems/region/if/ident */
+
 /**
- * @brief RTEMS Return Region Segment
+ * @ingroup RTEMSAPIClassicRegion
+ *
+ * @brief Identifies a region by the object name.
+ *
+ * @param name is the object name to look up.
  *
- * 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.
+ * @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.
  *
- * @param[in] id is the region id
- * @param[in] segment is the pointer to segment address
+ * This directive obtains a region identifier associated with the region name
+ * specified in ``name``.
  *
- * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful
+ * @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_return_segment(
-  rtems_id    id,
-  void       *segment
-);
+rtems_status_code rtems_region_ident( rtems_name name, rtems_id *id );
+
+/* Generated from spec:/rtems/region/if/resize-segment */
 
 /**
- * @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 %
+ *
+ * @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
+  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
-/* end of include file */
+#endif /* _RTEMS_RTEMS_REGION_H */