Generate <rtems/rtems/region.h>

1 files changed, 139 insertions, 174 deletions

diff --git a/cpukit/include/rtems/rtems/region.h b/cpukit/include/rtems/rtems/region.h
index 65866ced7b..2a8ec081d5 100644
--- a/cpukit/include/rtems/rtems/region.h
+++ b/cpukit/include/rtems/rtems/region.h
@@ -1,22 +1,52 @@
+/* SPDX-License-Identifier: BSD-2-Clause */
+
 /**
  * @file
  *
- * @ingroup ClassicRegion
+ * @ingroup RTEMSAPIClassicRegion
  *
- * @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 was automatically generated.  Do not edit it manually.
+ * Please have a look 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/branches/master/eng/req/howto.html
+ *
+ * for information how to maintain and re-generate this file.
  */
 
 #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>
@@ -28,243 +58,178 @@ extern "C" {
 #endif
 
 /**
- *  @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.
  */
-/**@{*/
 
 /**
- *  @brief rtems_region_create
+ * @ingroup RTEMSAPIClassicRegion
+ *
+ * @brief %
  *
- *  Region Manager
+ * @param name %
  *
- *  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 starting_address %
+ *
+ * @param length %
+ *
+ * @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
 );
 
 /**
- * @brief RTEMS Extend Region
- *
- * 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.
+ * @ingroup RTEMSAPIClassicRegion
  *
- * @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
+ * @brief %
  *
- * @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 );
 
 /**
- * @brief RTEMS Region Name to Id
+ * @ingroup RTEMSAPIClassicRegion
+ *
+ * @brief %
  *
- * 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.
+ * @param id %
  *
- * @param[in] name is the user defined region name
- * @param[in] id is the pointer to region id
+ * @param starting_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 id will
- *         be filled in with the region id.
+ * @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
 );
 
 /**
- * @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
 );
 
 /**
- * @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
 );
 
 /**
- * @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
 );
 
 /**
- * @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
 );
 
 /**
- * @brief RTEMS Return Region Segment
+ * @ingroup RTEMSAPIClassicRegion
  *
- * 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.
+ * @brief %
  *
- * @param[in] id is the region id
- * @param[in] segment is the pointer to segment address
+ * @param name %
  *
- * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful
+ * @param id %
  */
-rtems_status_code rtems_region_return_segment(
-  rtems_id    id,
-  void       *segment
-);
+rtems_status_code rtems_region_ident( rtems_name name, rtems_id *id );
 
 /**
- * @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
 );
 
-/**@}*/
+/**
+ * @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 */