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, 189 insertions, 175 deletions

diff --git a/cpukit/include/rtems/rtems/region.h b/cpukit/include/rtems/rtems/region.h
index 65866ced7b..f87c39623d 100644
--- a/cpukit/include/rtems/rtems/region.h
+++ b/cpukit/include/rtems/rtems/region.h
@@ -1,22 +1,56 @@
+/* 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 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:
  *
- * 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/branches/master/user/support/bugs.html
+ *
+ * For information on updating and regenerating please refer to:
+ *
+ * https://docs.rtems.org/branches/master/eng/req/howto.html
  */
 
+/* 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 +61,224 @@
 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 %
+ *
+ * @param name %
+ *
+ * @param starting_address %
  *
- *  Region Manager
+ * @param length %
  *
- *  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.
+ * @param page_size %
+ *
+ * @param attribute_set %
+ *
+ * @param id %
  */
 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
  *
- * 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.
+ * @brief %
  *
- * @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
- *
- * @retval This method returns RTEMS_SUCCESSFUL if there was not an
- *         error. Otherwise, a status code is returned indicating the
- *         source of the error.
+ * @param id %
  */
-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
  *
- * This routine implements the rtems_region_get_segment_size directive. It
- * returns the size in bytes of the specified user memory area.
+ * @brief %
  *
- * @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 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 size will
- *         be filled in with the segment size in bytes.
+ * @param segment %
+ *
+ * @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 object by the specified object name.
+ *
+ * This directive obtains the region identifier associated with the region name
+ * specified in ``name``.
+ *
+ * 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
+ * region identifier is used with other region related directives to access the
+ * region.
+ *
+ * The objects are searched from lowest to the highest index.  Only the local
+ * node is searched.
+ *
+ * @param name is the object name to look up.
+ *
+ * @param[out] id is the pointer to an object identifier variable.  The object
+ *   identifier of an object with the specified name will be stored in this
+ *   variable, in case of a successful operation.
+ *
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
  *
- * 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.
+ * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL.
  *
- * @param[in] id is the region id
- * @param[in] segment is the pointer to segment address
+ * @retval ::RTEMS_INVALID_NAME The ``name`` parameter was 0.
  *
- * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful
+ * @retval ::RTEMS_INVALID_NAME There was no object with the specified name on
+ *   the local node.
  */
-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 */