Design for atomic variable initialization.

EMBB-517

base_c/include/embb/base/c/atomic.h

@@ -85,9 +85,27 @@
 
 
 #ifdef DOXYGEN
 #ifdef DOXYGEN
 /**
 /**
+ * Initializes an atomic variable.
+ *
+ * \pre The atomic variable has not been initialized.
+ * \post The atomic variable has the value \c initial_value and can be used in
+ *       atomic operations.
+ *
+ * \ingroup C_BASE_ATOMIC
+ * \notthreadsafe
+ */
+void embb_atomic_init(
+  emb_atomic_TYPE* variable,
+  /**< [IN,OUT] Pointer to atomic variable to be initialized. */
+  TYPE initial_value
+  /**< [IN] Initial value to be assigned to atomic variable. */
+  );
+
+/**
  * Computes the logical "and" of the value stored in \p variable and \c value.
  * Computes the logical "and" of the value stored in \p variable and \c value.
  *
  *
- * The result is stored in \p variable.
+ * \pre The atomic variable has been initialized with \c embb_atomic_init
+ * \post The result is stored in \p variable.
  *
  *
  * \see \ref general_desc_atomic_base "Detailed description" for general
  * \see \ref general_desc_atomic_base "Detailed description" for general
  * information and the meaning of \b TYPE.
  * information and the meaning of \b TYPE.
@@ -95,12 +113,12 @@
  * \ingroup C_BASE_ATOMIC
  * \ingroup C_BASE_ATOMIC
  * \waitfree
  * \waitfree
  */
  */
-EMBB_PLATFORM_INLINE void embb_atomic_and_assign_TYPE(
+void embb_atomic_and_assign_TYPE(
   embb_atomic_TYPE* variable,
   embb_atomic_TYPE* variable,
   /**< [IN,OUT] Pointer to atomic variable which serves as left-hand side for
   /**< [IN,OUT] Pointer to atomic variable which serves as left-hand side for
                 the "and" operation and is used to store the result. */
                 the "and" operation and is used to store the result. */
   TYPE value
   TYPE value
-  /** [IN] Right-hand side of "and" operation, passed by value */
+  /**< [IN] Right-hand side of "and" operation, passed by value */
   );
   );
 
 
 /**
 /**
@@ -111,6 +129,8 @@ EMBB_PLATFORM_INLINE void embb_atomic_and_assign_TYPE(
  * to the value of \p expected. Otherwise, stores the value of \p variable in
  * to the value of \p expected. Otherwise, stores the value of \p variable in
  * \p expected.
  * \p expected.
  *
  *
+ * \pre The atomic variable has been initialized with \c embb_atomic_init
+ *
  * \return != 0 if the values of \p variable and \p expected were equivalent \n
  * \return != 0 if the values of \p variable and \p expected were equivalent \n
  *          0 otherwise
  *          0 otherwise
  *
  *
@@ -120,7 +140,7 @@ EMBB_PLATFORM_INLINE void embb_atomic_and_assign_TYPE(
  * \ingroup C_BASE_ATOMIC
  * \ingroup C_BASE_ATOMIC
  * \waitfree
  * \waitfree
  */
  */
-EMBB_PLATFORM_INLINE int embb_atomic_compare_and_swap_TYPE(
+int embb_atomic_compare_and_swap_TYPE(
   embb_atomic_TYPE* variable,
   embb_atomic_TYPE* variable,
   /**< [IN,OUT] Pointer to atomic variable */
   /**< [IN,OUT] Pointer to atomic variable */
   TYPE* expected,
   TYPE* expected,
@@ -132,6 +152,8 @@ EMBB_PLATFORM_INLINE int embb_atomic_compare_and_swap_TYPE(
 /**
 /**
  * Adds \p value to \p variable and returns its old value.
  * Adds \p value to \p variable and returns its old value.
  *
  *
+ * \pre The atomic variable has been initialized with \c embb_atomic_init
+ *
  * \return The value before the operation
  * \return The value before the operation
  *
  *
  * \see \ref general_desc_atomic_base "Detailed description" for general
  * \see \ref general_desc_atomic_base "Detailed description" for general
@@ -140,7 +162,7 @@ EMBB_PLATFORM_INLINE int embb_atomic_compare_and_swap_TYPE(
  * \ingroup C_BASE_ATOMIC
  * \ingroup C_BASE_ATOMIC
  * \waitfree
  * \waitfree
  */
  */
-EMBB_PLATFORM_INLINE TYPE embb_atomic_fetch_and_add_TYPE(
+TYPE embb_atomic_fetch_and_add_TYPE(
   embb_atomic_TYPE* variable,
   embb_atomic_TYPE* variable,
   /**< [IN,OUT] Pointer to atomic variable*/
   /**< [IN,OUT] Pointer to atomic variable*/
   TYPE value
   TYPE value
@@ -150,6 +172,8 @@ EMBB_PLATFORM_INLINE TYPE embb_atomic_fetch_and_add_TYPE(
 /**
 /**
  * Loads the value of \p variable and returns it.
  * Loads the value of \p variable and returns it.
  *
  *
+ * \pre The atomic variable has been initialized with \c embb_atomic_init
+ *
  * \return The value of the atomic variable.
  * \return The value of the atomic variable.
  *
  *
  * \see \ref general_desc_atomic_base "Detailed description" for general
  * \see \ref general_desc_atomic_base "Detailed description" for general
@@ -158,7 +182,7 @@ EMBB_PLATFORM_INLINE TYPE embb_atomic_fetch_and_add_TYPE(
  * \ingroup C_BASE_ATOMIC
  * \ingroup C_BASE_ATOMIC
  * \waitfree
  * \waitfree
  */
  */
-EMBB_PLATFORM_INLINE TYPE embb_atomic_load_TYPE(
+TYPE embb_atomic_load_TYPE(
   const embb_atomic_TYPE* variable
   const embb_atomic_TYPE* variable
   /**< [IN] Pointer to atomic variable */
   /**< [IN] Pointer to atomic variable */
   );
   );
@@ -169,12 +193,13 @@ EMBB_PLATFORM_INLINE TYPE embb_atomic_load_TYPE(
  * \ingroup C_BASE_ATOMIC
  * \ingroup C_BASE_ATOMIC
  * \waitfree
  * \waitfree
  */
  */
-EMBB_PLATFORM_INLINE void embb_atomic_memory_barrier();
+void embb_atomic_memory_barrier();
 
 
 /**
 /**
  * Computes the logical "or" of the value stored in \p variable and \c value.
  * Computes the logical "or" of the value stored in \p variable and \c value.
  *
  *
- * The result is stored in \p variable.
+ * \pre The atomic variable has been initialized with \c embb_atomic_init
+ * \post The result is stored in \p variable.
  *
  *
  * \see \ref general_desc_atomic_base "Detailed description" for general
  * \see \ref general_desc_atomic_base "Detailed description" for general
  * information and the meaning of \b TYPE.
  * information and the meaning of \b TYPE.
@@ -182,7 +207,7 @@ EMBB_PLATFORM_INLINE void embb_atomic_memory_barrier();
  * \ingroup C_BASE_ATOMIC
  * \ingroup C_BASE_ATOMIC
  * \waitfree
  * \waitfree
  */
  */
-EMBB_PLATFORM_INLINE void embb_atomic_or_assign_TYPE(
+void embb_atomic_or_assign_TYPE(
   embb_atomic_TYPE* variable,
   embb_atomic_TYPE* variable,
   /**< [IN,OUT] Pointer to atomic variable which serves as left-hand side for
   /**< [IN,OUT] Pointer to atomic variable which serves as left-hand side for
                 the "or" operation and is used to store the result. */
                 the "or" operation and is used to store the result. */
@@ -193,13 +218,15 @@ EMBB_PLATFORM_INLINE void embb_atomic_or_assign_TYPE(
 /**
 /**
  * Stores \p value in \p variable.
  * Stores \p value in \p variable.
  *
  *
+ * \pre The atomic variable has been initialized with \c embb_atomic_init
+ *
  * \see \ref general_desc_atomic_base "Detailed description" for general
  * \see \ref general_desc_atomic_base "Detailed description" for general
  * information and the meaning of \b TYPE.
  * information and the meaning of \b TYPE.
  *
  *
  * \ingroup C_BASE_ATOMIC
  * \ingroup C_BASE_ATOMIC
  * \waitfree
  * \waitfree
  */
  */
-EMBB_PLATFORM_INLINE void embb_atomic_store_TYPE(
+void embb_atomic_store_TYPE(
   embb_atomic_TYPE* variable,
   embb_atomic_TYPE* variable,
   /**< [IN,OUT] Pointer to atomic variable */
   /**< [IN,OUT] Pointer to atomic variable */
   int value
   int value
@@ -209,6 +236,8 @@ EMBB_PLATFORM_INLINE void embb_atomic_store_TYPE(
 /**
 /**
  * Swaps the current value of \p variable with \p value.
  * Swaps the current value of \p variable with \p value.
  *
  *
+ * \pre The atomic variable has been initialized with \c embb_atomic_init
+ *
  * \return The old value of \p variable
  * \return The old value of \p variable
  *
  *
  * \see \ref general_desc_atomic_base "Detailed description" for general
  * \see \ref general_desc_atomic_base "Detailed description" for general
@@ -217,7 +246,7 @@ EMBB_PLATFORM_INLINE void embb_atomic_store_TYPE(
  * \ingroup C_BASE_ATOMIC
  * \ingroup C_BASE_ATOMIC
  * \waitfree
  * \waitfree
  */
  */
-EMBB_PLATFORM_INLINE TYPE embb_atomic_swap_TYPE(
+TYPE embb_atomic_swap_TYPE(
   embb_atomic_TYPE* variable,
   embb_atomic_TYPE* variable,
   /**< [IN,OUT] Pointer to atomic variable whose value is swapped */
   /**< [IN,OUT] Pointer to atomic variable whose value is swapped */
   TYPE value
   TYPE value
@@ -227,7 +256,8 @@ EMBB_PLATFORM_INLINE TYPE embb_atomic_swap_TYPE(
 /**
 /**
 * Computes the logical "xor" of the value stored in \p variable and \c value.
 * Computes the logical "xor" of the value stored in \p variable and \c value.
 *
 *
-* The result is stored in \p variable.
+* \pre The atomic variable has been initialized with \c embb_atomic_init
+* \post The result is stored in \p variable.
 *
 *
 * \see \ref general_desc_atomic_base "Detailed description" for general
 * \see \ref general_desc_atomic_base "Detailed description" for general
 * information and the meaning of \b TYPE.
 * information and the meaning of \b TYPE.
@@ -235,7 +265,7 @@ EMBB_PLATFORM_INLINE TYPE embb_atomic_swap_TYPE(
 * \ingroup C_BASE_ATOMIC
 * \ingroup C_BASE_ATOMIC
 * \waitfree
 * \waitfree
 */
 */
-EMBB_PLATFORM_INLINE void embb_atomic_xor_assign_TYPE(
+void embb_atomic_xor_assign_TYPE(
   embb_atomic_TYPE* variable,
   embb_atomic_TYPE* variable,
   /**< [IN,OUT] Pointer to atomic variable which serves as left-hand side for
   /**< [IN,OUT] Pointer to atomic variable which serves as left-hand side for
                 the "xor" operation and is used to store the result. */
                 the "xor" operation and is used to store the result. */

base_c/include/embb/base/c/internal/atomic/init.h

+/*
+ * Copyright (c) 2014-2015, Siemens AG. All rights reserved.
+ *
+ * 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 HOLDER 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 EMBB_BASE_C_INTERNAL_ATOMIC_INIT_H_
+#define EMBB_BASE_C_INTERNAL_ATOMIC_INIT_H_
+
+// TODO implementation of embb_atomic_init()
+
+#endif // EMBB_BASE_C_INTERNAL_ATOMIC_INIT_H_