Commit 983feb43 by bernhard-gatzhammer

Design for atomic variable initialization.

EMBB-517
parent d36f1bdb
...@@ -85,9 +85,27 @@ ...@@ -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 @@ ...@@ -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( ...@@ -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( ...@@ -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( ...@@ -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( ...@@ -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( ...@@ -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( ...@@ -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( ...@@ -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(); ...@@ -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( ...@@ -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( ...@@ -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( ...@@ -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( ...@@ -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( ...@@ -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. */
......
/*
* 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_
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or sign in to comment