Generate <rtems/score/basedefs.h>

1 files changed, 565 insertions, 333 deletions

diff --git a/cpukit/include/rtems/score/basedefs.h b/cpukit/include/rtems/score/basedefs.h
index c31b4ebef7..b3f77fa0f5 100644
--- a/cpukit/include/rtems/score/basedefs.h
+++ b/cpukit/include/rtems/score/basedefs.h
@@ -1,161 +1,216 @@
+/* SPDX-License-Identifier: BSD-2-Clause */
+
 /**
  * @file
  *
- * @ingroup RTEMSScore
+ * @ingroup RTEMSAPI
+ * @ingroup RTEMSAPIBaseDefs
  *
- * @brief Basic Definitions
+ * @brief This header file provides basic definitions used by the API and the
+ *   implementation.
  */
 
 /*
- *  COPYRIGHT (c) 1989-2007.
- *  On-Line Applications Research Corporation (OAR).
+ * Copyright (C) 2014 Paval Pisa
+ * Copyright (C) 2011, 2013 On-Line Applications Research Corporation (OAR)
+ * Copyright (C) 2009, 2020 embedded brains GmbH (http://www.embedded-brains.de)
  *
- *  Copyright (C) 2010, 2019 embedded brains GmbH
+ * 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.
  *
- *  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.
+ * 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.
  */
 
-#ifndef _RTEMS_BASEDEFS_H
-#define _RTEMS_BASEDEFS_H
-
-/**
- * @defgroup RTEMSScoreBaseDefs Basic Definitions
+/*
+ * This file was automatically generated.  Do not edit it manually.
+ * Please have a look at
  *
- * @ingroup RTEMSScore
+ * https://docs.rtems.org/branches/master/eng/req/howto.html
  *
- * @{
+ * for information how to maintain and re-generate this file.
  */
 
+#ifndef _RTEMS_SCORE_BASEDEFS_H
+#define _RTEMS_SCORE_BASEDEFS_H
+
 #include <rtems/score/cpuopts.h>
 
-#ifndef ASM
-  #include <stddef.h>
+#if !defined(ASM)
   #include <stdbool.h>
+  #include <stddef.h>
   #include <stdint.h>
 #endif
 
-#ifndef TRUE
-  /**
-   *  This ensures that RTEMS has TRUE defined in all situations.
-   */
-  #define TRUE 1
+#ifdef __cplusplus
+extern "C" {
 #endif
 
-#ifndef FALSE
-  /**
-   *  This ensures that RTEMS has FALSE defined in all situations.
-   */
-  #define FALSE 0
-#endif
+/**
+ * @defgroup RTEMSAPI API
+ *
+ * @brief API
+ *
+ * This group contains the RTEMS Application Programming Interface (API).
+ */
 
-#if TRUE == FALSE
-  #error "TRUE equals FALSE"
-#endif
+/**
+ * @defgroup RTEMSAPIBaseDefs Base Definitions
+ *
+ * @ingroup RTEMSAPI
+ *
+ * @brief This group contains basic macros and defines to give access to
+ *   compiler-specific features.
+ */
 
 /**
- *  The following (in conjunction with compiler arguments) are used
- *  to choose between the use of static inline functions and macro
- *  functions.   The static inline implementation allows better
- *  type checking with no cost in code size or execution speed.
+ * @ingroup RTEMSAPIBaseDefs
+ *
+ * @brief Concatenates _x and _y without expanding.
+ *
+ * @param _x is the left hand side token of the concatenation.
+ *
+ * @param _y is the right hand side token of the concatenation.
+ *
+ * @return The concatenation of the tokens _x and _y.
  */
-#ifdef __GNUC__
-  #define RTEMS_INLINE_ROUTINE static __inline__
-#else
-  #define RTEMS_INLINE_ROUTINE static inline
+#define RTEMS_CONCAT( _x, _y ) _x##_y
+
+#if !defined(ASM)
+  /**
+   * @brief A not implemented function to trigger compile time errors with an
+   *   error message.
+   */
+  #if defined(__GNUC__)
+    __attribute__((__error__("RTEMS_DEQUALIFY() types differ not only by volatile and const"))) void *
+    RTEMS_DEQUALIFY_types_not_compatible( void );
+  #else
+    void *RTEMS_DEQUALIFY_types_not_compatible( void );
+  #endif
 #endif
 
 /**
- *  The following macro is a compiler specific way to ensure that memory
- *  writes are not reordered around certain points.  This specifically can
- *  impact interrupt disable and thread dispatching critical sections.
+ * @ingroup RTEMSAPIBaseDefs
+ *
+ * @brief Returns the type of a pointer reference of the specified level to the
+ *   specified type.
+ *
+ * The reference type idea is based on libHX by Jan Engelhardt.
+ *
+ * @param _level is the pointer indirection level expressed in *.
+ *
+ * @param _target is the reference target type.
  */
-#ifdef __GNUC__
-  #define RTEMS_COMPILER_MEMORY_BARRIER() __asm__ volatile("" ::: "memory")
+#if defined(__GNUC__)
+  #define RTEMS_TYPEOF_REFX( _level, _target ) \
+    __typeof__(_level(union { int z; __typeof__(_target) x; }){0}.x)
 #else
-  #define RTEMS_COMPILER_MEMORY_BARRIER()
+  #define RTEMS_TYPEOF_REFX( _level, _target )
 #endif
 
 /**
- *  The following defines a compiler specific attribute which informs
- *  the compiler that the method must not be inlined.
+ * @ingroup RTEMSAPIBaseDefs
+ *
+ * @brief Stringifies _x without expanding.
+ *
+ * @param _x is the token to stringify.
+ *
+ * @return The stringification of the token _x.
  */
-#ifdef __GNUC__
-  #define RTEMS_NO_INLINE __attribute__((__noinline__))
-#else
-  #define RTEMS_NO_INLINE
-#endif
+#define RTEMS_STRING( _x ) #_x
 
 /**
- *  The following macro is a compiler specific way to indicate that
- *  the method will NOT return to the caller.  This can assist the
- *  compiler in code generation and avoid unreachable paths.  This
- *  can impact the code generated following calls to
- *  rtems_fatal_error_occurred and _Terminate.
+ * @ingroup RTEMSAPIBaseDefs
+ *
+ * @brief Concatenates expansion of _x and expansion of _y.
+ *
+ * @param _x is expanded first and then used as the left hand side token of the
+ *   concatenation.
+ *
+ * @param _y is expanded first and then used as the right hand side token of
+ *   the concatenation.
+ *
+ * @return The concatenation of the expansions of tokens _x and _y.
  */
-#if defined(RTEMS_SCHEDSIM)
-  #define RTEMS_NO_RETURN
-#elif defined(__GNUC__) && !defined(RTEMS_DEBUG)
-  #define RTEMS_NO_RETURN __attribute__((__noreturn__))
-#else
-  #define RTEMS_NO_RETURN
-#endif
+#define RTEMS_XCONCAT( _x, _y ) RTEMS_CONCAT( _x, _y )
 
-/* Provided for backward compatibility */
-#define RTEMS_COMPILER_NO_RETURN_ATTRIBUTE RTEMS_NO_RETURN
+/**
+ * @ingroup RTEMSAPIBaseDefs
+ *
+ * @brief Helper macro to perform a macro expansion on the specified token.
+ *
+ * @param _token is the token to expand.
+ */
+#define RTEMS_EXPAND( _token ) _token
 
 /**
- *  The following defines a compiler specific attribute which informs
- *  the compiler that the method has no effect except the return value
- *  and that the return value depends only the value of parameters.
+ * @ingroup RTEMSAPIBaseDefs
+ *
+ * @brief Instructs the compiler in a declaration to issue a warning whenever a
+ *   variable, function, or type using this declaration will be used.
  */
-#ifdef __GNUC__
-  #define RTEMS_CONST __attribute__((__const__))
+#if defined(__GNUC__)
+  #define RTEMS_DEPRECATED __attribute__((__deprecated__))
 #else
-  #define RTEMS_CONST
+  #define RTEMS_DEPRECATED
 #endif
 
 /**
- *  The following defines a compiler specific attribute which informs
- *  the compiler that the method has no effect except the return value
- *  and that the return value depends only on parameters and/or global
- *  variables.
+ * @ingroup RTEMSAPIBaseDefs
+ *
+ * @brief Tells the compiler in a function declaration that this function does
+ *   not return.
  */
-#ifdef __GNUC__
-  #define RTEMS_PURE __attribute__((__pure__))
+#if defined(__GNUC__)
+  #define RTEMS_NO_RETURN __attribute__((__noreturn__))
 #else
-  #define RTEMS_PURE
+  #define RTEMS_NO_RETURN
 #endif
 
-/* Provided for backward compatibility */
-#define RTEMS_COMPILER_PURE_ATTRIBUTE RTEMS_PURE
-
 /**
- *  Instructs the compiler to issue a warning whenever a variable or function
- *  with this attribute will be used.
+ * @ingroup RTEMSAPIBaseDefs
+ *
+ * @brief Instructs the compiler in a type definition to place members of a
+ *   structure or union so that the memory required is minimized.
  */
-#ifdef __GNUC__
-  #define RTEMS_DEPRECATED __attribute__((__deprecated__))
+#if defined(__GNUC__)
+  #define RTEMS_PACKED __attribute__((__packed__))
 #else
-  #define RTEMS_DEPRECATED
+  #define RTEMS_PACKED
 #endif
 
-/* Provided for backward compatibility */
-#define RTEMS_COMPILER_DEPRECATED_ATTRIBUTE RTEMS_DEPRECATED
-
 /**
- * @brief Instructs the compiler to place a specific variable or function in
- * the specified section.
+ * @ingroup RTEMSAPIBaseDefs
+ *
+ * @brief Tells the compiler in a function declaration that this function has
+ *   no effect except the return value and that the return value depends only
+ *   on the value of parameters and/or global variables.
  */
 #if defined(__GNUC__)
-  #define RTEMS_SECTION( _section ) __attribute__((__section__(_section)))
+  #define RTEMS_PURE __attribute__((__pure__))
 #else
-  #define RTEMS_SECTION( _section )
+  #define RTEMS_PURE
 #endif
 
 /**
- * @brief Instructs the compiler that a specific variable or function is used.
+ * @ingroup RTEMSAPIBaseDefs
+ *
+ * @brief Tells the compiler that a specific variable or function is used.
  */
 #if defined(__GNUC__)
   #define RTEMS_USED __attribute__((__used__))
@@ -164,62 +219,84 @@
 #endif
 
 /**
- *  Instructs the compiler that a specific variable is deliberately unused.
- *  This can occur when reading volatile device memory or skipping arguments
- *  in a variable argument method.
- */
-#if defined(__GNUC__)
-  #define RTEMS_UNUSED __attribute__((__unused__))
+ * @ingroup RTEMSAPIBaseDefs
+ *
+ * @brief Performs a type cast which removes qualifiers without warnings to the
+ *   specified type for the specified variable.
+ *
+ * @param _ptr_level is the pointer indirection level expressed in *.
+ *
+ * @param _type is the target type of the cast.
+ *
+ * @param _var is the variable.
+ */
+#if defined(__cplusplus)
+  #define RTEMS_DEQUALIFY_DEPTHX( _ptr_level, _type, _var ) \
+    (const_cast<_type>(_var))
+#elif defined(__GNUC__)
+  #define RTEMS_DEQUALIFY_DEPTHX( _ptr_level, _type, _var ) \
+    __builtin_choose_expr(__builtin_types_compatible_p( \
+        RTEMS_TYPEOF_REFX(_ptr_level, _var), \
+        RTEMS_TYPEOF_REFX(_ptr_level, _type) \
+      ) || __builtin_types_compatible_p(_type, void *), \
+    (_type)(_var), \
+    RTEMS_DEQUALIFY_types_not_compatible())
 #else
-  #define RTEMS_UNUSED
+  #define RTEMS_DEQUALIFY_DEPTHX( _ptr_level, _type, _var ) \
+    ((_type)(uintptr_t)(const volatile void *)(_var))
 #endif
 
-/* Provided for backward compatibility */
-#define RTEMS_COMPILER_UNUSED_ATTRIBUTE RTEMS_UNUSED
-
 /**
- *  Instructs the compiler that a specific structure or union members will be
- *  placed so that the least memory is used.
+ * @ingroup RTEMSAPIBaseDefs
+ *
+ * @brief Stringifies the expansion of _x.
+ *
+ * @param _x is the token expand and stringify.
+ *
+ * @return The stringification of the expansion of token _x.
  */
-#if defined(__GNUC__)
-  #define RTEMS_PACKED __attribute__((__packed__))
-#else
-  #define RTEMS_PACKED
-#endif
+#define RTEMS_XSTRING( _x ) RTEMS_STRING( _x )
 
 /**
- * @brief Instructs the compiler to generate an alias to the specified target
- * function.
+ * @ingroup RTEMSAPIBaseDefs
+ *
+ * @brief Constructs a symbol name.
+ *
+ * @param _name is the user defined name of the symbol.  The name shall be a
+ *   valid designator.  On the name a macro expansion is performed.
  */
-#if defined(__GNUC__)
-  #define RTEMS_ALIAS( _target ) __attribute__((__alias__(#_target)))
+#if defined(__USER_LABEL_PREFIX__)
+  #define RTEMS_SYMBOL_NAME( _name ) RTEMS_XCONCAT(__USER_LABEL_PREFIX__, _name)
 #else
-  #define RTEMS_ALIAS( _target )
+  #define RTEMS_SYMBOL_NAME( _name ) RTEMS_EXPAND(_name)
 #endif
 
 /**
- * @brief Instructs the compiler to define a weak function.
- *
- * Use this attribute for function definitions.  Do not use it for function
- * declarations.
+ * @brief Asserts that this program point is unreachable.
  */
-#if defined(__GNUC__)
-  #define RTEMS_WEAK __attribute__((__weak__))
+#if defined(RTEMS_DEBUG)
+  #define _Assert_Unreachable() _Assert( 0 )
 #else
-  #define RTEMS_WEAK
+  #define _Assert_Unreachable() do { } while ( 0 )
 #endif
 
 /**
- * @brief Instructs the compiler to generate a weak alias to the specified
- * target function.
+ * @ingroup RTEMSAPIBaseDefs
+ *
+ * @brief Instructs the compiler to generate an alias to the specified target
+ *   function.
+ *
+ * @param _target is the target function name.
  */
 #if defined(__GNUC__)
-  #define RTEMS_WEAK_ALIAS( _target ) __attribute__((__weak__, __alias__(#_target)))
+  #define RTEMS_ALIAS( _target ) __attribute__((__alias__(#_target)))
 #else
-  #define RTEMS_WEAK_ALIAS( _target )
+  #define RTEMS_ALIAS( _target )
 #endif
 
 /**
+ * @ingroup RTEMSAPIBaseDefs
+ *
  * @brief Returns the specified value aligned down to the specified alignment.
  *
  * @param _value is the value to align down.
@@ -235,6 +312,8 @@
   ( ( _value ) & ~( ( _alignment ) - 1 ) )
 
 /**
+ * @ingroup RTEMSAPIBaseDefs
+ *
  * @brief Returns the specified value aligned up to the specified alignment.
  *
  * @param _value is the value to align up.
@@ -250,7 +329,12 @@
   ( ( ( _value ) + ( _alignment ) - 1 ) & ~( ( _alignment ) - 1 ) )
 
 /**
- * @brief Instructs the compiler to enforce the specified alignment.
+ * @ingroup RTEMSAPIBaseDefs
+ *
+ * @brief Instructs the compiler in a declaration or definition to enforce the
+ *   specified alignment.
+ *
+ * @param _alignment is the desired alignment in bytes.
  */
 #if defined(__GNUC__)
   #define RTEMS_ALIGNED( _alignment ) __attribute__((__aligned__(_alignment)))
@@ -258,140 +342,181 @@
   #define RTEMS_ALIGNED( _alignment )
 #endif
 
-/* Provided for backward compatibility */
-#define RTEMS_COMPILER_PACKED_ATTRIBUTE RTEMS_PACKED
-
-#if defined(RTEMS_DEBUG) && !defined(RTEMS_SCHEDSIM)
-  #define _Assert_Unreachable() _Assert( 0 )
-#else
-  #define _Assert_Unreachable() do { } while ( 0 )
-#endif
-
 /**
- * @brief Tells the compiler that this program point is unreachable.
+ * @ingroup RTEMSAPIBaseDefs
+ *
+ * @brief Tells the compiler in a declaration that the memory allocation
+ *   alignment parameter of this function is similar to aligned_alloc().
+ *
+ * @param _index is the allocation alignment parameter index (starting with
+ *   one).
  */
-#if defined(__GNUC__) && !defined(RTEMS_SCHEDSIM)
-  #define RTEMS_UNREACHABLE() \
-    do { \
-      __builtin_unreachable(); \
-      _Assert_Unreachable(); \
-    } while ( 0 )
+#if defined(__GNUC__)
+  #define RTEMS_ALLOC_ALIGN( _index ) __attribute__((__alloc_align__(_index)))
 #else
-  #define RTEMS_UNREACHABLE() _Assert_Unreachable()
+  #define RTEMS_ALLOC_ALIGN( _index )
 #endif
 
 /**
- * @brief Tells the compiler that this function expects printf()-like
- * arguments.
+ * @ingroup RTEMSAPIBaseDefs
+ *
+ * @brief Tells the compiler in a declaration that the memory allocation size
+ *   parameter of this function is similar to malloc().
+ *
+ * @param _index is the allocation size parameter index (starting with one).
  */
 #if defined(__GNUC__)
-  #define RTEMS_PRINTFLIKE( _format_pos, _ap_pos ) \
-    __attribute__((__format__(__printf__, _format_pos, _ap_pos)))
+  #define RTEMS_ALLOC_SIZE( _index ) __attribute__((__alloc_size__(_index)))
 #else
-  #define RTEMS_PRINTFLIKE( _format_pos, _ap_pos )
+  #define RTEMS_ALLOC_SIZE( _index )
 #endif
 
 /**
- * @brief Tells the compiler that this function is a memory allocation function
- * similar to malloc().
+ * @ingroup RTEMSAPIBaseDefs
+ *
+ * @brief Tells the compiler in a declaration that the memory allocation item
+ *   count and item size parameter of this function is similar to calloc().
+ *
+ * @param _count_index is the allocation item count parameter index (starting
+ *   with one).
+ *
+ * @param _size_index is the allocation item size parameter index (starting
+ *   with one).
  */
 #if defined(__GNUC__)
-  #define RTEMS_MALLOCLIKE __attribute__((__malloc__))
+  #define RTEMS_ALLOC_SIZE_2( _count_index, _size_index ) \
+    __attribute__((__alloc_size__(_count_index, _size_index)))
 #else
-  #define RTEMS_MALLOCLIKE
+  #define RTEMS_ALLOC_SIZE_2( _count_index, _size_index )
 #endif
 
 /**
- * @brief Tells the compiler the memory allocation size parameter of this
- * function similar to malloc().
+ * @ingroup RTEMSAPIBaseDefs
+ *
+ * @brief Returns the element count of the specified array.
+ *
+ * @param _array is the name of the array.
+ *
+ * @return The element count of the specified array.
  */
-#if defined(__GNUC__)
-  #define RTEMS_ALLOC_SIZE( _index ) __attribute__((__alloc_size__(_index)))
-#else
-  #define RTEMS_ALLOC_SIZE( _index )
-#endif
+#define RTEMS_ARRAY_SIZE( _array ) (sizeof(_array) / sizeof((_array)[0]))
 
 /**
- * @brief Tells the compiler the memory allocation item count and item size
- * parameter of this function similar to calloc().
+ * @ingroup RTEMSAPIBaseDefs
+ *
+ * @brief Provided for backward compatibility.
  */
-#if defined(__GNUC__)
-  #define RTEMS_ALLOC_SIZE_2( _count_index, _size_index ) \
-     __attribute__((__alloc_size__(_count_index, _size_index)))
-#else
-  #define RTEMS_ALLOC_SIZE_2( _count_index, _size_index )
-#endif
+#define RTEMS_COMPILER_DEPRECATED_ATTRIBUTE RTEMS_DEPRECATED
 
 /**
- * @brief Tells the compiler the memory allocation alignment parameter of this
- * function similar to aligned_alloc().
+ * @ingroup RTEMSAPIBaseDefs
+ *
+ * @brief This macro forbids the compiler to reorder read and write commands
+ *   around it.
  */
 #if defined(__GNUC__)
-  #define RTEMS_ALLOC_ALIGN( _index ) __attribute__((__alloc_align__(_index)))
+  #define RTEMS_COMPILER_MEMORY_BARRIER() __asm__ volatile( "" ::: "memory" )
 #else
-  #define RTEMS_ALLOC_ALIGN( _index )
+  #define RTEMS_COMPILER_MEMORY_BARRIER() do { } while ( 0 )
 #endif
 
 /**
- * @brief Tells the compiler that the result of this function should be used.
+ * @ingroup RTEMSAPIBaseDefs
+ *
+ * @brief Provided for backward compatibility.
  */
-#if defined(__GNUC__)
-  #define RTEMS_WARN_UNUSED_RESULT __attribute__((__warn_unused_result__))
-#else
-  #define RTEMS_WARN_UNUSED_RESULT
-#endif
+#define RTEMS_COMPILER_NO_RETURN_ATTRIBUTE RTEMS_NO_RETURN
 
 /**
- * @brief Obfuscates the variable so that the compiler cannot perform
- * optimizations based on the variable value.
+ * @ingroup RTEMSAPIBaseDefs
  *
- * The variable must be simple enough to fit into a register.
+ * @brief Provided for backward compatibility.
+ */
+#define RTEMS_COMPILER_PACKED_ATTRIBUTE RTEMS_PACKED
+
+/**
+ * @ingroup RTEMSAPIBaseDefs
+ *
+ * @brief Provided for backward compatibility.
+ */
+#define RTEMS_COMPILER_PURE_ATTRIBUTE RTEMS_PURE
+
+/**
+ * @ingroup RTEMSAPIBaseDefs
+ *
+ * @brief Provided for backward compatibility.
+ */
+#define RTEMS_COMPILER_USED_ATTRIBUTE RTEMS_USED
+
+/**
+ * @ingroup RTEMSAPIBaseDefs
+ *
+ * @brief Tells the compiler in a function declaration that this function has
+ *   no effect except the return value and that the return value depends only
+ *   on the value of parameters.
  */
 #if defined(__GNUC__)
-  #define RTEMS_OBFUSCATE_VARIABLE( _var ) __asm__("" : "+r" (_var))
+  #define RTEMS_CONST __attribute__((__const__))
 #else
-  #define RTEMS_OBFUSCATE_VARIABLE( _var ) (void) (_var)
+  #define RTEMS_CONST
 #endif
 
 /**
+ * @ingroup RTEMSAPIBaseDefs
+ *
+ * @brief Returns the pointer to the container of a specified member pointer.
+ *
+ * @param _m is the pointer to a member of the container.
+ *
+ * @param _type is the type of the container.
+ *
+ * @param _member_name is the designator name of the container member.
+ *
+ * @return Returns the pointer to the container of a specified member pointer.
+ */
+#define RTEMS_CONTAINER_OF( _m, _type, _member_name ) \
+  ( (_type *) ( (uintptr_t) ( _m ) - offsetof( _type, _member_name ) ) )
+
+/**
+ * @ingroup RTEMSAPIBaseDefs
+ *
  * @brief Declares a global symbol with the specified name.
  *
  * This macro must be placed at file scope.
  *
- * The name must be a valid designator.
+ * @param _name is the name of the global symbol.  It shall be a valid
+ *   designator.
  */
-#define RTEMS_DECLARE_GLOBAL_SYMBOL( _name ) \
-  extern char _name[]
+#define RTEMS_DECLARE_GLOBAL_SYMBOL( _name ) extern char _name[]
 
 /**
- * @brief Constructs a symbol name.
+ * @ingroup RTEMSAPIBaseDefs
  *
- * @param _name The user defined name of the symbol.  The name shall be a valid
- *   designator.  On the name a macro expansion is performed.
+ * @brief Performs a type cast which removes const qualifiers without warnings
+ *   to the specified type for the specified pointer variable.
+ *
+ * @param _type is the target type of the cast.
+ *
+ * @param _var is the pointer variable.
  */
-#if defined(__USER_LABEL_PREFIX__)
-  #define RTEMS_SYMBOL_NAME( _name ) \
-    RTEMS_XCONCAT( __USER_LABEL_PREFIX__, _name )
-#else
-  /* Helper to perform the macro expansion */
-  #define _RTEMS_SYMBOL_NAME( _name ) _name
-
-  #define RTEMS_SYMBOL_NAME( _name ) _RTEMS_SYMBOL_NAME( _name )
-#endif
+#define RTEMS_DECONST( _type, _var ) RTEMS_DEQUALIFY_DEPTHX(*, _type, _var)
 
 /**
+ * @ingroup RTEMSAPIBaseDefs
+ *
  * @brief Defines a global symbol with the specified name and value.
  *
  * This macro shall be placed at file scope.
  *
- * @param _name The user defined name of the symbol.  The name shall be a valid
- *   designator.  On the name a macro expansion is performed and afterwards it
- *   is stringified.
- * @param _value The value of the symbol.  On the value a macro expansion is
+ * @param _name is the user defined name of the symbol.  The name shall be a
+ *   valid designator.  On the name a macro expansion is performed and
+ *   afterwards it is stringified.
+ *
+ * @param _value is the value of the symbol.  On the value a macro expansion is
  *   performed and afterwards it is stringified.  It shall expand to an integer
  *   expression understood by the assembler.
  */
-#if defined(__GNUC__)
+#if defined(__USER_LABEL_PREFIX__)
   #define RTEMS_DEFINE_GLOBAL_SYMBOL( _name, _value ) \
     __asm__( \
       "\t.globl " RTEMS_XSTRING( RTEMS_SYMBOL_NAME( _name ) ) \
@@ -403,197 +528,304 @@
 #endif
 
 /**
- * @brief Returns the value of the specified integral expression and tells the
- * compiler that the predicted value is true (1).
+ * @ingroup RTEMSAPIBaseDefs
  *
- * @param[in] _exp The expression.
+ * @brief Performs a type cast which removes all qualifiers without warnings to
+ *   the specified type for the specified pointer variable.
  *
- * @return The value of the expression.
+ * @param _type is the target type of the cast.
+ *
+ * @param _var is the pointer variable.
  */
-#if defined(__GNUC__)
-  #define RTEMS_PREDICT_TRUE( _exp ) __builtin_expect( ( _exp ), 1 )
-#else
-  #define RTEMS_PREDICT_TRUE( _exp ) ( _exp )
+#define RTEMS_DEQUALIFY( _type, _var ) RTEMS_DEQUALIFY_DEPTHX(*, _type, _var)
+
+/**
+ * @ingroup RTEMSAPIBaseDefs
+ *
+ * @brief Performs a type cast which removes volatile qualifiers without
+ *   warnings to the specified type for the specified pointer variable.
+ *
+ * @param _type is the target type of the cast.
+ *
+ * @param _var is the pointer variable.
+ */
+#define RTEMS_DEVOLATILE( _type, _var ) RTEMS_DEQUALIFY_DEPTHX(*, _type, _var)
+
+#if !defined(FALSE)
+  /**
+   * @ingroup RTEMSAPIBaseDefs
+   *
+   * @brief If FALSE is undefined, then FALSE is defined to 0.
+   */
+  #define FALSE 0
 #endif
 
 /**
- * @brief Returns the value of the specified integral expression and tells the
- * compiler that the predicted value is false (0).
+ * @ingroup RTEMSAPIBaseDefs
  *
- * @param[in] _exp The expression.
+ * @brief Evaluates to true if the specified members of two types have
+ *   compatible types, otherwise to false.
  *
- * @return The value of the expression.
+ * @param _t_lhs is the left hand side type.
+ *
+ * @param _m_lhs is the left hand side member.
+ *
+ * @param _t_rhs is the right hand side type.
+ *
+ * @param _m_rhs is the right hand side member.
  */
 #if defined(__GNUC__)
-  #define RTEMS_PREDICT_FALSE( _exp ) __builtin_expect( ( _exp ), 0 )
+  #define RTEMS_HAVE_MEMBER_SAME_TYPE( _t_lhs, _m_lhs, _t_rhs, _m_rhs ) \
+    __builtin_types_compatible_p( \
+      __typeof__( ( (_t_lhs *) 0 )->_m_lhs ), \
+      __typeof__( ( (_t_rhs *) 0 )->_m_rhs ) \
+    )
 #else
-  #define RTEMS_PREDICT_FALSE( _exp ) ( _exp )
+  #define RTEMS_HAVE_MEMBER_SAME_TYPE( _t_lhs, _m_lhs, _t_rhs, _m_rhs ) true
 #endif
 
 /**
- * @brief Returns the return address of the current function.
+ * @ingroup RTEMSAPIBaseDefs
  *
- * @return The return address.
+ * @brief Gives a hint to the compiler in a function declaration to inline this
+ *   function.
  */
 #if defined(__GNUC__)
-  #define RTEMS_RETURN_ADDRESS() __builtin_return_address( 0 )
+  #define RTEMS_INLINE_ROUTINE static __inline__
 #else
-  #define RTEMS_RETURN_ADDRESS() NULL
+  #define RTEMS_INLINE_ROUTINE static inline
 #endif
 
-#if __cplusplus >= 201103L
-  #define RTEMS_STATIC_ASSERT(cond, msg) \
-    static_assert(cond, # msg)
-#elif __STDC_VERSION__ >= 201112L
-  #define RTEMS_STATIC_ASSERT(cond, msg) \
-    _Static_assert(cond, # msg)
+/**
+ * @ingroup RTEMSAPIBaseDefs
+ *
+ * @brief Tells the compiler in a declaration that this function is a memory
+ *   allocation function similar to malloc().
+ */
+#if defined(__GNUC__)
+  #define RTEMS_MALLOCLIKE __attribute__((__malloc__))
 #else
-  #define RTEMS_STATIC_ASSERT(cond, msg) \
-    struct rtems_static_assert_ ## msg \
-      { int rtems_static_assert_ ## msg : (cond) ? 1 : -1; }
+  #define RTEMS_MALLOCLIKE
 #endif
 
-#define RTEMS_ARRAY_SIZE(array) (sizeof(array) / sizeof((array)[0]))
-
-/*
- * Zero-length arrays are valid in C99 as flexible array members.  C++11
- * doesn't allow flexible array members.  Use the GNU extension which is also
- * supported by other compilers.
+/**
+ * @ingroup RTEMSAPIBaseDefs
+ *
+ * @brief Instructs the compiler in a function declaration to not inline this
+ *   function.
  */
-#if __STDC_VERSION__ >= 199409L
-  #define RTEMS_ZERO_LENGTH_ARRAY
+#if defined(__GNUC__)
+  #define RTEMS_NO_INLINE __attribute__((__noinline__))
 #else
-  #define RTEMS_ZERO_LENGTH_ARRAY 0
+  #define RTEMS_NO_INLINE
 #endif
 
 /**
- * @brief Returns a pointer to the container of a specified member pointer.
+ * @ingroup RTEMSAPIBaseDefs
+ *
+ * @brief Obfuscates the variable so that the compiler cannot perform
+ *   optimizations based on the variable value.
  *
- * @param[in] _m The pointer to a member of the container.
- * @param[in] _type The type of the container.
- * @param[in] _member_name The designator name of the container member.
+ * The variable must be simple enough to fit into a register.
+ *
+ * @param _var is the variable to obfuscate.
  */
-#define RTEMS_CONTAINER_OF( _m, _type, _member_name ) \
-  ( (_type *) ( (uintptr_t) ( _m ) - offsetof( _type, _member_name ) ) )
+#if defined(__GNUC__)
+  #define RTEMS_OBFUSCATE_VARIABLE( _var ) __asm__( "" : "+r" ( _var ) )
+#else
+  #define RTEMS_OBFUSCATE_VARIABLE( _var ) (void) (_var)
+#endif
 
-#ifdef __cplusplus
-#define RTEMS_DEQUALIFY_DEPTHX( _ptr_level, _type, _var ) \
-            (const_cast<_type>( _var ))
-#else /* Standard C code */
-
-/* The reference type idea based on libHX by Jan Engelhardt */
-#define RTEMS_TYPEOF_REFX(_ptr_level, _ptr_type) \
-  __typeof__(_ptr_level(union { int z; __typeof__(_ptr_type) x; }){0}.x)
-
-#if defined(__GNUC__) && !defined(ASM)
-#if  ((__GNUC__ * 1000 + __GNUC_MINOR__) >= 4004)
-extern void* RTEMS_DEQUALIFY_types_not_compatible(void)
-  __attribute__((error ("RTEMS_DEQUALIFY types differ not only by volatile and const")));
-#else
-extern void RTEMS_DEQUALIFY_types_not_compatible(void);
-#endif
-#define RTEMS_DEQUALIFY_DEPTHX( _ptr_level, _type, _var ) ( \
-    __builtin_choose_expr( __builtin_types_compatible_p ( \
-        RTEMS_TYPEOF_REFX( _ptr_level, _var ), \
-        RTEMS_TYPEOF_REFX( _ptr_level, _type ) \
-      ) || __builtin_types_compatible_p ( _type, void * ), \
-    (_type)(_var), \
-    RTEMS_DEQUALIFY_types_not_compatible() \
-  ) \
-)
-#endif /*__GNUC__*/
-#endif /*__cplusplus*/
+/**
+ * @ingroup RTEMSAPIBaseDefs
+ *
+ * @brief Returns the value of the specified integral expression and tells the
+ *   compiler that the predicted value is false (1).
+ *
+ * @param _exp is the expression.
+ *
+ * @return The value of the expression.
+ */
+#if defined(__GNUC__)
+  #define RTEMS_PREDICT_FALSE( _exp ) __builtin_expect( ( _exp ), 0 )
+#else
+  #define RTEMS_PREDICT_FALSE( _exp ) ( _exp )
+#endif
 
-#ifndef RTEMS_DECONST
-#ifdef RTEMS_DEQUALIFY_DEPTHX
-#define RTEMS_DECONST( _type, _var ) \
-  RTEMS_DEQUALIFY_DEPTHX( *, _type, _var )
-#else /*RTEMS_DEQUALIFY_DEPTHX*/
 /**
- * @brief Removes the const qualifier from a type of a variable.
+ * @ingroup RTEMSAPIBaseDefs
+ *
+ * @brief Returns the value of the specified integral expression and tells the
+ *   compiler that the predicted value is true (1).
+ *
+ * @param _exp is the expression.
  *
- * @param[in] _type The target type for the variable.
- * @param[in] _var The variable.
+ * @return The value of the expression.
  */
-#define RTEMS_DECONST( _type, _var ) \
-  ((_type)(uintptr_t)(const void *) ( _var ))
+#if defined(__GNUC__)
+  #define RTEMS_PREDICT_TRUE( _exp ) __builtin_expect( ( _exp ), 1 )
+#else
+  #define RTEMS_PREDICT_TRUE( _exp ) ( _exp )
+#endif
 
-#endif /*RTEMS_DEQUALIFY_DEPTHX*/
-#endif /*RTEMS_DECONST*/
+/**
+ * @ingroup RTEMSAPIBaseDefs
+ *
+ * @brief Tells the compiler in a declaration that this function expects
+ *   printf()-like arguments.
+ *
+ * @param _format_pos is the position of the format parameter index (starting
+ *   with one).
+ *
+ * @param _ap_pos is the position of the argument pointer parameter index
+ *   (starting with one).
+ */
+#if defined(__GNUC__)
+  #define RTEMS_PRINTFLIKE( _format_pos, _ap_pos ) \
+    __attribute__((__format__(__printf__, _format_pos, _ap_pos)))
+#else
+  #define RTEMS_PRINTFLIKE( _format_pos, _ap_pos )
+#endif
 
-#ifndef RTEMS_DEVOLATILE
-#ifdef RTEMS_DEQUALIFY_DEPTHX
-#define RTEMS_DEVOLATILE( _type, _var ) \
-  RTEMS_DEQUALIFY_DEPTHX( *, _type, _var )
-#else /*RTEMS_DEQUALIFY_DEPTHX*/
 /**
- * @brief Removes the volatile qualifier from a type of a variable.
+ * @ingroup RTEMSAPIBaseDefs
+ *
+ * @brief Returns the return address of the current function.
  *
- * @param[in] _type The target type for the variable.
- * @param[in] _var The variable.
+ * @return The return address of the current function.
  */
-#define RTEMS_DEVOLATILE( _type, _var ) \
-  ((_type)(uintptr_t)(volatile void *) ( _var ))
+#if defined(__GNUC__)
+  #define RTEMS_RETURN_ADDRESS() __builtin_return_address(0)
+#else
+  #define RTEMS_RETURN_ADDRESS() NULL
+#endif
 
-#endif /*RTEMS_DEQUALIFY_DEPTHX*/
-#endif /*RTEMS_DEVOLATILE*/
+/**
+ * @ingroup RTEMSAPIBaseDefs
+ *
+ * @brief Instructs the compiler to place a specific variable or function in
+ *   the specified section.
+ *
+ * @param _section is the section name as a string.
+ */
+#if defined(__GNUC__)
+  #define RTEMS_SECTION( _section ) __attribute__((__section__(_section)))
+#else
+  #define RTEMS_SECTION( _section )
+#endif
 
-#ifndef RTEMS_DEQUALIFY
-#ifdef RTEMS_DEQUALIFY_DEPTHX
-#define RTEMS_DEQUALIFY( _type, _var ) \
-  RTEMS_DEQUALIFY_DEPTHX( *, _type, _var )
-#else /*RTEMS_DEQUALIFY_DEPTHX*/
 /**
- * @brief Removes the all qualifiers from a type of a variable.
+ * @ingroup RTEMSAPIBaseDefs
+ *
+ * @brief Asserts at compile time that the specified condition is satisfied.
+ *
+ * @param _cond is the condition this static assertion shall satisfy.
  *
- * @param[in] _type The target type for the variable.
- * @param[in] _var The variable.
+ * @param _msg is the error message in case the static assertion fails.
  */
-#define RTEMS_DEQUALIFY( _type, _var ) \
-  ((_type)(uintptr_t)(const volatile void *) ( _var ))
+#if __cplusplus >= 201103L
+  #define RTEMS_STATIC_ASSERT( _cond, _msg ) static_assert(_cond, # _msg)
+#elif __STDC_VERSION__ >= 201112L
+  #define RTEMS_STATIC_ASSERT( _cond, _msg ) _Static_assert(_cond, # _msg)
+#else
+  #define RTEMS_STATIC_ASSERT( _cond, _msg ) \
+    struct rtems_static_assert_ ## _msg \
+      { int rtems_static_assert_ ## _msg : (_cond) ? 1 : -1; }
+#endif
 
-#endif /*RTEMS_DEQUALIFY_DEPTHX*/
-#endif /*RTEMS_DEQUALIFY*/
+#if !defined(TRUE)
+  /**
+   * @ingroup RTEMSAPIBaseDefs
+   *
+   * @brief If TRUE is undefined, then TRUE is defined to 1.
+   */
+  #define TRUE 1
+#endif
 
 /**
- * @brief Evaluates to true if the members of two types have the same type.
+ * @brief Tells the compiler that this program point is unreachable.
+ */
+#if defined(__GNUC__)
+  #define RTEMS_UNREACHABLE() \
+    do { \
+      __builtin_unreachable(); \
+      _Assert_Unreachable(); \
+    } while ( 0 )
+#else
+  #define RTEMS_UNREACHABLE() _Assert_Unreachable()
+#endif
+
+/**
+ * @ingroup RTEMSAPIBaseDefs
  *
- * @param[in] _t_lhs Left hand side type.
- * @param[in] _m_lhs Left hand side member.
- * @param[in] _t_rhs Right hand side type.
- * @param[in] _m_rhs Right hand side member.
+ * @brief Tells the compiler that a specific variable or function is
+ *   deliberately unused.
  */
-#ifdef __GNUC__
-  #define RTEMS_HAVE_MEMBER_SAME_TYPE( _t_lhs, _m_lhs, _t_rhs, _m_rhs ) \
-    __builtin_types_compatible_p( \
-      __typeof__( ( (_t_lhs *) 0 )->_m_lhs ), \
-      __typeof__( ( (_t_rhs *) 0 )->_m_rhs ) \
-    )
+#if defined(__GNUC__)
+  #define RTEMS_UNUSED __attribute__((__unused__))
 #else
-  #define RTEMS_HAVE_MEMBER_SAME_TYPE( _t_lhs, _m_lhs, _t_rhs, _m_rhs ) \
-    true
+  #define RTEMS_UNUSED
 #endif
 
 /**
- * @brief Concatenates _x and _y without expanding.
+ * @ingroup RTEMSAPIBaseDefs
+ *
+ * @brief Tells the compiler in a declaration that the result of this function
+ *   should be used.
  */
-#define RTEMS_CONCAT( _x, _y ) _x##_y
+#if defined(__GNUC__)
+  #define RTEMS_WARN_UNUSED_RESULT __attribute__((__warn_unused_result__))
+#else
+  #define RTEMS_WARN_UNUSED_RESULT
+#endif
 
 /**
- * @brief Concatenates expansion of _x and expansion of _y.
+ * @ingroup RTEMSAPIBaseDefs
+ *
+ * @brief Tells the compiler in a function definition that this function should
+ *   be weak.
+ *
+ * Use this attribute for function definitions.  Do not use it for function
+ * declarations.
  */
-#define RTEMS_XCONCAT( _x, _y ) RTEMS_CONCAT( _x, _y )
+#if defined(__GNUC__)
+  #define RTEMS_WEAK __attribute__((__weak__))
+#else
+  #define RTEMS_WEAK
+#endif
 
 /**
- * @brief Stringifies _x  without expanding.
+ * @ingroup RTEMSAPIBaseDefs
+ *
+ * @brief Instructs the compiler to generate a weak alias to the specified
+ *   target function.
+ *
+ * @param _target is the target function name.
  */
-#define RTEMS_STRING( _x ) #_x
+#if defined(__GNUC__)
+  #define RTEMS_WEAK_ALIAS( _target ) \
+    __attribute__((__weak__, __alias__(#_target)))
+#else
+  #define RTEMS_WEAK_ALIAS( _target )
+#endif
 
 /**
- * @brief Stringifies expansion of _x.
+ * @ingroup RTEMSAPIBaseDefs
+ *
+ * @brief This is a constant to declare zero-length arrays.
+ *
+ * Zero-length arrays are valid in C99 as flexible array members.  C++11 does
+ * not allow flexible array members.  Use the GNU extension which is also
+ * supported by other compilers.
  */
-#define RTEMS_XSTRING( _x ) RTEMS_STRING( _x )
+#if __STDC_VERSION__ >= 199409L
+  #define RTEMS_ZERO_LENGTH_ARRAY
+#else
+  #define RTEMS_ZERO_LENGTH_ARRAY 0
+#endif
 
-/** @} */
+#ifdef __cplusplus
+}
+#endif
 
-#endif /* _RTEMS_BASEDEFS_H */
+#endif /* _RTEMS_SCORE_BASEDEFS_H */