rtems: Generate <rtems/rtems/support.h>

Change license to BSD-2-Clause according to file histories and
documentation re-licensing agreement.

Update #3899.
Update #3993.

1 files changed, 320 insertions, 84 deletions

diff --git a/cpukit/include/rtems/rtems/support.h b/cpukit/include/rtems/rtems/support.h
index 92dd49076f..829548aae2 100644
--- a/cpukit/include/rtems/rtems/support.h
+++ b/cpukit/include/rtems/rtems/support.h
@@ -1,168 +1,404 @@
+/* SPDX-License-Identifier: BSD-2-Clause */
+
 /**
  * @file
  *
- * @ingroup ClassicRTEMSWorkspace
+ * @brief This header file defines support services of the API.
  */
 
-/* COPYRIGHT (c) 1989-2008.
- * On-Line Applications Research Corporation (OAR).
+/*
+ * 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:
  *
- * 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/support/if/header */
+
 #ifndef _RTEMS_RTEMS_SUPPORT_H
 #define _RTEMS_RTEMS_SUPPORT_H
 
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+#include <rtems/config.h>
 #include <rtems/rtems/types.h>
 #include <rtems/score/heapinfo.h>
-#include <rtems/config.h>
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+/* Generated from spec:/rtems/support/if/group */
+
 /**
- * @addtogroup ClassicTasks
+ * @defgroup RTEMSAPIClassicSupport Support Services
+ *
+ * @ingroup RTEMSAPIClassic
+ *
+ * @brief Items of this group should move to other groups.
  */
-/**@{**/
+
+/* Generated from spec:/rtems/support/if/is-name-valid */
 
 /**
- * @brief Returns the number of micro seconds for the milli seconds value @a _ms.
+ * @ingroup RTEMSAPIClassicSupport
+ *
+ * @brief Checks if the object name is valid.
+ *
+ * @param name is the object name to check.
+ *
+ * @return Returns true, if the object name is valid, otherwise false.
+ *
+ * @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
  */
-#define RTEMS_MILLISECONDS_TO_MICROSECONDS(_ms) ((_ms) * 1000UL)
+static inline bool rtems_is_name_valid( rtems_name name )
+{
+  return name != 0;
+}
+
+/* Generated from spec:/rtems/support/if/microseconds-to-ticks */
 
 /**
- * @brief Returns the number of ticks for the milli seconds value @a _ms.
+ * @ingroup RTEMSAPIClassicSupport
+ *
+ * @brief Gets the number of clock ticks for the microseconds value.
+ *
+ * @param _us is the microseconds value to convert to clock ticks.
+ *
+ * @return Returns the number of clock ticks for the specified microseconds
+ *   value.
+ *
+ * @par Notes
+ * The number of clock ticks per second is defined by the
+ * #CONFIGURE_MICROSECONDS_PER_TICK application configuration option.
+ *
+ * @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
  */
-#define RTEMS_MILLISECONDS_TO_TICKS(_ms) \
-       (RTEMS_MILLISECONDS_TO_MICROSECONDS(_ms) / \
-          rtems_configuration_get_microseconds_per_tick())
+#define RTEMS_MICROSECONDS_TO_TICKS( _us ) \
+  ( ( _us ) / rtems_configuration_get_microseconds_per_tick() )
+
+/* Generated from spec:/rtems/support/if/milliseconds-to-microseconds */
 
 /**
- * @brief Returns the number of ticks for the micro seconds value @a _us.
+ * @ingroup RTEMSAPIClassicSupport
+ *
+ * @brief Gets the number of microseconds for the milliseconds value.
+ *
+ * @param _ms is the milliseconds value to convert to microseconds.
+ *
+ * @return Returns the number of microseconds for the milliseconds value.
+ *
+ * @par Constraints
+ * @parblock
+ * The following constraints apply to this directive:
+ *
+ * * The directive is implemented by a macro and may be called from within
+ *   C/C++ constant expressions.  In addition, a function implementation of the
+ *   directive exists for bindings to other programming languages.
+ *
+ * * The directive will not cause the calling task to be preempted.
+ * @endparblock
  */
-#define RTEMS_MICROSECONDS_TO_TICKS(_us) \
-       ((_us) / rtems_configuration_get_microseconds_per_tick())
+#define RTEMS_MILLISECONDS_TO_MICROSECONDS( _ms ) ( ( _ms ) * 1000UL )
+
+/* Generated from spec:/rtems/support/if/milliseconds-to-ticks */
 
 /**
- * @brief Returns @c true if the name is valid, and @c false otherwise.
+ * @ingroup RTEMSAPIClassicSupport
+ *
+ * @brief Gets the number of clock ticks for the milliseconds value.
+ *
+ * @param _ms is the milliseconds value to convert to clock ticks.
+ *
+ * @return Returns the number of clock ticks for the milliseconds value.
+ *
+ * @par Notes
+ * The number of clock ticks per second is defined by the
+ * #CONFIGURE_MICROSECONDS_PER_TICK application configuration option.
+ *
+ * @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_INLINE_ROUTINE bool rtems_is_name_valid (
-  rtems_name name
-)
-{
-  return ( name != 0 );
-}
+#define RTEMS_MILLISECONDS_TO_TICKS( _ms ) \
+  RTEMS_MICROSECONDS_TO_TICKS( RTEMS_MILLISECONDS_TO_MICROSECONDS( _ms ) )
+
+/* Generated from spec:/rtems/support/if/name-to-characters */
 
 /**
- * @brief Breaks the object name into the four component characters @a c1,
- * @a c2, @a c3, and @a c4.
+ * @ingroup RTEMSAPIClassicSupport
+ *
+ * @brief Breaks the object name into the four component characters.
+ *
+ * @param name is the object name to break into four component characters.
+ *
+ * @param[out] c1 is the first character of the object name.
+ *
+ * @param[out] c2 is the second character of the object name.
+ *
+ * @param[out] c3 is the third character of the object name.
+ *
+ * @param[out] c4 is the fourth character of the object name.
+ *
+ * @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_INLINE_ROUTINE void rtems_name_to_characters(
-  rtems_name    name,
-  char         *c1,
-  char         *c2,
-  char         *c3,
-  char         *c4
+static inline void rtems_name_to_characters(
+  rtems_name name,
+  char      *c1,
+  char      *c2,
+  char      *c3,
+  char      *c4
 )
 {
-  *c1 = (char) ((name >> 24) & 0xff);
-  *c2 = (char) ((name >> 16) & 0xff);
-  *c3 = (char) ((name >> 8) & 0xff);
-  *c4 = (char) ( name & 0xff);
+  *c1 = (char) ( ( ( name ) >> 24 ) & 0xff );
+  *c2 = (char) ( ( ( name ) >> 16 ) & 0xff );
+  *c3 = (char) ( ( ( name ) >> 8 ) & 0xff );
+  *c4 = (char) ( ( name ) & 0xff );
 }
 
-/** @} */
+/* Generated from spec:/rtems/support/if/workspace-allocate */
 
 /**
- * @defgroup ClassicRTEMSWorkspace Workspace
+ * @ingroup RTEMSAPIClassicSupport
  *
- * @ingroup RTEMSAPIClassic
+ * @brief Allocates a memory area from the RTEMS Workspace.
  *
- * Workspace definitions.
- */
-/**@{**/
-
-/**
- * @brief Gets Workspace Information
+ * @param bytes is the number of bytes to allocated.
+ *
+ * @param[out] pointer is the pointer to a pointer variable.  When the
+ *   directive call is successful, the begin address of the allocated memory
+ *   area will be stored in this variable.
+ *
+ * @return Returns true, if the allocation was successful, otherwise false.
  *
- * Returns information about the heap that is used as the RTEMS Executive
- * Workspace in @a the_info.
+ * @par Notes
+ * This directive is intended to be used by tests of the RTEMS test suites.
  *
- * Returns @c true if successful, and @a false otherwise.
+ * @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
  */
-bool rtems_workspace_get_information(
-  Heap_Information_block  *the_info
-);
+bool rtems_workspace_allocate( size_t bytes, void **pointer );
+
+/* Generated from spec:/rtems/support/if/workspace-free */
 
 /**
- * @brief Allocates Memory from the Workspace
+ * @ingroup RTEMSAPIClassicSupport
+ *
+ * @brief Frees the memory area allocated from the RTEMS Workspace.
+ *
+ * @param pointer is the begin address of the memory area to free.
  *
- * A number of @a bytes bytes will be allocated from the RTEMS Executive
- * Workspace and returned in @a pointer.
+ * @return Returns true, if freeing the memory area was successful, otherwise
+ *   false.
  *
- * Returns @c true if successful, and @a false otherwise.
+ * @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
  */
-bool rtems_workspace_allocate(
-  size_t   bytes,
-  void   **pointer
-);
+bool rtems_workspace_free( void *pointer );
+
+/* Generated from spec:/rtems/support/if/workspace-get-information */
 
 /**
- * @brief Frees Memory Allocated from the Workspace
+ * @ingroup RTEMSAPIClassicSupport
+ *
+ * @brief Gets information about the RTEMS Workspace.
  *
- * This frees the memory indicated by @a pointer that was allocated from the
- * RTEMS Executive Workspace.
+ * @param the_info is the pointer to a heap information variable.  When the
+ *   directive call is successful, the heap information will be stored in this
+ *   variable.
  *
- * Returns @c true if successful, and @a false otherwise.
+ * @return Returns true, if getting the information was successful, otherwise
+ *   false.
+ *
+ * @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
  */
-bool rtems_workspace_free(
-  void *pointer
-);
+bool rtems_workspace_get_information( Heap_Information_block *the_info );
+
+/* Generated from spec:/rtems/support/if/workspace-greedy-allocate */
 
 /**
- * @brief Greedy allocate that empties the workspace.
+ * @ingroup RTEMSAPIClassicSupport
+ *
+ * @brief Greedy allocates that empties the RTEMS Workspace.
  *
- * Afterwards the heap has at most @a block_count allocatable blocks of sizes
- * specified by @a block_sizes.  The @a block_sizes must point to an array with
- * @a block_count members.  All other blocks are used.
+ * @param block_sizes is the array of block sizes.
  *
- * @see rtems_workspace_greedy_free().
+ * @param block_count is the block count.
+ *
+ * Afterwards the heap has at most ``block_count`` allocatable blocks of sizes
+ * specified by ``block_sizes``.  The ``block_sizes`` must point to an array
+ * with ``block_count`` members.  All other blocks are used.
+ *
+ * @return The returned pointer value may be used to free the greedy allocation
+ *   by calling rtems_workspace_greedy_free().
  */
 void *rtems_workspace_greedy_allocate(
   const uintptr_t *block_sizes,
-  size_t block_count
+  size_t           block_count
 );
 
+/* Generated from spec:/rtems/support/if/workspace-greedy-allocate-all-except-largest */
+
 /**
- * @brief Greedy allocate all blocks except the largest free block.
+ * @ingroup RTEMSAPIClassicSupport
+ *
+ * @brief Greedy allocates all blocks of the RTEMS Workspace except the largest
+ *   free block.
+ *
+ * @param allocatable_size is the remaining allocatable size.
  *
  * Afterwards the heap has at most one allocatable block.  This block is the
  * largest free block if it exists.  The allocatable size of this block is
- * stored in @a allocatable_size.  All other blocks are used.
+ * stored in ``allocatable_size``.  All other blocks are used.
+ *
+ * @return The returned pointer value may be used to free the greedy allocation
+ *   by calling rtems_workspace_greedy_free().
  *
- * @see rtems_workspace_greedy_free().
+ * @par Notes
+ * This directive is intended to be used by tests of the RTEMS test suites.
+ *
+ * @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
  */
 void *rtems_workspace_greedy_allocate_all_except_largest(
   uintptr_t *allocatable_size
 );
 
+/* Generated from spec:/rtems/support/if/workspace-greedy-free */
+
 /**
- * @brief Frees space of a greedy allocation.
+ * @ingroup RTEMSAPIClassicSupport
+ *
+ * @brief Frees space of a greedy allocation to the RTEMS Workspace.
+ *
+ * @param opaque is the pointer value returned by
+ *   rtems_workspace_greedy_allocate() or
+ *   rtems_workspace_greedy_allocate_all_except_largest().
  *
- * The @a opaque argument must be the return value of
- * rtems_workspace_greedy_allocate() or
- * rtems_workspace_greedy_allocate_all_except_largest().
+ * @par Notes
+ * This directive is intended to be used by tests of the RTEMS test suites.
+ *
+ * @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
  */
 void rtems_workspace_greedy_free( void *opaque );
 
-/** @} */
-
 #ifdef __cplusplus
 }
 #endif
 
-#endif
-/* end of include file */
+#endif /* _RTEMS_RTEMS_SUPPORT_H */