api: atomic: clean atomic API documentation

Refined and centralized comment about relaxed memory ordering.
Removed in/out doxygen tags since 'atom' pointer to an object
that application must not directly access (only through the API).

Signed-off-by: Petri Savolainen <petri.savolainen@nokia.com>
Reviewed-by: Mike Holmes <mike.holmes@linaro.org>
Signed-off-by: Maxim Uvarov <maxim.uvarov@linaro.org>

1 files changed, 48 insertions, 64 deletions

diff --git a/include/odp/api/atomic.h b/include/odp/api/atomic.h
index 8aacc9d62..97e86392b 100644
--- a/include/odp/api/atomic.h
+++ b/include/odp/api/atomic.h
@@ -18,10 +18,20 @@
 extern "C" {
 #endif
 
-/** @defgroup odp_atomic ODP ATOMIC
- *  Atomic types and relaxed operations. These operations cannot be used for
- *  synchronization.
- *  @{
+/**
+ * @defgroup odp_atomic ODP ATOMIC
+ * @details
+ * <b> Atomic integers </b>
+ *
+ * Atomic integer types (odp_atomic_u32_t and odp_atomic_u64_t) can be used to
+ * implement e.g. shared counters. If not otherwise documented, operations in
+ * this API are implemented using <b> RELAXED memory ordering </b> (see memory
+ * order descriptions in the C11 specification). Relaxed operations do not
+ * provide synchronization or ordering for other memory accesses (initiated
+ * before or after the operation), only atomicity of the operation itself is
+ * guaranteed.
+ *
+ * @{
  */
 
 /**
@@ -34,19 +44,16 @@ extern "C" {
 
 /**
  * Initialize atomic uint32 variable
- * @note Relaxed memory order, cannot be used for synchronization
  *
- * @param[out] atom Pointer to an atomic uint32 variable
- * @param val Value to initialize the variable with
+ * @param atom    Pointer to atomic variable
+ * @param val     Value to initialize the variable with
  */
 void odp_atomic_init_u32(odp_atomic_u32_t *atom, uint32_t val);
 
-
 /**
  * Load value of atomic uint32 variable
- * @note Relaxed memory order, cannot be used for synchronization
  *
- * @param atom Pointer to an atomic uint32 variable
+ * @param atom    Pointer to atomic variable
  *
  * @return Value of the variable
  */
@@ -54,19 +61,17 @@ uint32_t odp_atomic_load_u32(odp_atomic_u32_t *atom);
 
 /**
  * Store value to atomic uint32 variable
- * @note Relaxed memory order, cannot be used for synchronization
  *
- * @param[out] atom Pointer to an atomic uint32 variable
- * @param val Value to store in the variable
+ * @param atom    Pointer to atomic variable
+ * @param val     Value to store in the variable
  */
 void odp_atomic_store_u32(odp_atomic_u32_t *atom, uint32_t val);
 
 /**
  * Fetch and add to atomic uint32 variable
- * @note Relaxed memory order, cannot be used for synchronization
  *
- * @param[in,out] atom Pointer to an atomic uint32 variable
- * @param val Value to be added to the variable
+ * @param atom    Pointer to atomic variable
+ * @param val     Value to be added to the variable
  *
  * @return Value of the variable before the addition
  */
@@ -74,19 +79,17 @@ uint32_t odp_atomic_fetch_add_u32(odp_atomic_u32_t *atom, uint32_t val);
 
 /**
  * Add to atomic uint32 variable
- * @note Relaxed memory order, cannot be used for synchronization
  *
- * @param[in,out] atom Pointer to an atomic uint32 variable
- * @param val A value to be added to the variable
+ * @param atom    Pointer to atomic variable
+ * @param val     Value to be added to the variable
  */
 void odp_atomic_add_u32(odp_atomic_u32_t *atom, uint32_t val);
 
 /**
  * Fetch and subtract from atomic uint32 variable
- * @note Relaxed memory order, cannot be used for synchronization
  *
- * @param[in,out] atom Pointer to an atomic uint32 variable
- * @param val A value to be subracted from the variable
+ * @param atom    Pointer to atomic variable
+ * @param val     Value to be subracted from the variable
  *
  * @return Value of the variable before the subtraction
  */
@@ -94,37 +97,32 @@ uint32_t odp_atomic_fetch_sub_u32(odp_atomic_u32_t *atom, uint32_t val);
 
 /**
  * Subtract from atomic uint32 variable
- * @note Relaxed memory order, cannot be used for synchronization
  *
- * @param[in,out] atom Pointer to an atomic uint32 variable
- * @param val Value to be subtracted from the variable
+ * @param atom    Pointer to atomic variable
+ * @param val     Value to be subtracted from the variable
  */
 void odp_atomic_sub_u32(odp_atomic_u32_t *atom, uint32_t val);
 
 /**
  * Fetch and increment atomic uint32 variable
- * @note Relaxed memory order, cannot be used for synchronization
  *
- * @param[in,out] atom Pointer to an atomic uint32 variable
+ * @param atom    Pointer to atomic variable
  *
  * @return Value of the variable before the increment
  */
-
 uint32_t odp_atomic_fetch_inc_u32(odp_atomic_u32_t *atom);
 
 /**
  * Increment atomic uint32 variable
- * @note Relaxed memory order, cannot be used for synchronization
  *
- * @param[in,out] atom Pointer to an atomic uint32 variable
+ * @param atom    Pointer to atomic variable
  */
 void odp_atomic_inc_u32(odp_atomic_u32_t *atom);
 
 /**
  * Fetch and decrement atomic uint32 variable
- * @note Relaxed memory order, cannot be used for synchronization
  *
- * @param[in,out] atom Pointer to an atomic uint32 variable
+ * @param atom    Pointer to atomic variable
  *
  * @return Value of the variable before the subtraction
  */
@@ -132,26 +130,23 @@ uint32_t odp_atomic_fetch_dec_u32(odp_atomic_u32_t *atom);
 
 /**
  * Decrement atomic uint32 variable
- * @note Relaxed memory order, cannot be used for synchronization
  *
- * @param[in,out] atom Pointer to an atomic uint32 variable
+ * @param atom    Pointer to atomic variable
  */
 void odp_atomic_dec_u32(odp_atomic_u32_t *atom);
 
 /**
  * Initialize atomic uint64 variable
- * @note Relaxed memory order, cannot be used for synchronization
  *
- * @param[out] atom Pointer to an atomic uint64 variable
- * @param val Value to initialize the variable with
+ * @param atom    Pointer to atomic variable
+ * @param val     Value to initialize the variable with
  */
 void odp_atomic_init_u64(odp_atomic_u64_t *atom, uint64_t val);
 
 /**
  * Load value of atomic uint64 variable
- * @note Relaxed memory order, cannot be used for synchronization
  *
- * @param atom Pointer to an atomic uint64 variable
+ * @param atom    Pointer to atomic variable
  *
  * @return Value of the variable
  */
@@ -159,41 +154,35 @@ uint64_t odp_atomic_load_u64(odp_atomic_u64_t *atom);
 
 /**
  * Store value to atomic uint64 variable
- * @note Relaxed memory order, cannot be used for synchronization
  *
- * @param[out] atom Pointer to an atomic uint64 variable
- * @param val Value to store in the variable
+ * @param atom    Pointer to atomic variable
+ * @param val     Value to store in the variable
  */
 void odp_atomic_store_u64(odp_atomic_u64_t *atom, uint64_t val);
 
 /**
  * Fetch and add to atomic uint64 variable
- * @note Relaxed memory order, cannot be used for synchronization
  *
- * @param[in,out] atom Pointer to an atomic uint64 variable
- * @param val Value to be added to the variable
+ * @param atom    Pointer to atomic variable
+ * @param val     Value to be added to the variable
  *
  * @return Value of the variable before the addition
  */
-
 uint64_t odp_atomic_fetch_add_u64(odp_atomic_u64_t *atom, uint64_t val);
 
 /**
  * Add to atomic uint64 variable
- * @note Relaxed memory order, cannot be used for synchronization
- *
- * @param[in,out] atom Pointer to an atomic uint64 variable
- * @param val Value to be added to the variable
  *
+ * @param atom    Pointer to atomic variable
+ * @param val     Value to be added to the variable
  */
 void odp_atomic_add_u64(odp_atomic_u64_t *atom, uint64_t val);
 
 /**
  * Fetch and subtract from atomic uint64 variable
- * @note Relaxed memory order, cannot be used for synchronization
  *
- * @param[in,out] atom Pointer to an atomic uint64 variable
- * @param val Value to be subtracted from the variable
+ * @param atom    Pointer to atomic variable
+ * @param val     Value to be subtracted from the variable
  *
  * @return Value of the variable before the subtraction
  */
@@ -201,18 +190,16 @@ uint64_t odp_atomic_fetch_sub_u64(odp_atomic_u64_t *atom, uint64_t val);
 
 /**
  * Subtract from atomic uint64 variable
- * @note Relaxed memory order, cannot be used for synchronization
  *
- * @param[in,out] atom Pointer to an atomic uint64 variable
- * @param val Value to be subtracted from the variable
+ * @param atom    Pointer to atomic variable
+ * @param val     Value to be subtracted from the variable
  */
 void odp_atomic_sub_u64(odp_atomic_u64_t *atom, uint64_t val);
 
 /**
  * Fetch and increment atomic uint64 variable
- * @note Relaxed memory order, cannot be used for synchronization
  *
- * @param[in,out] atom Pointer to an atomic uint64 variable
+ * @param atom    Pointer to atomic variable
  *
  * @return Value of the variable before the increment
  */
@@ -220,17 +207,15 @@ uint64_t odp_atomic_fetch_inc_u64(odp_atomic_u64_t *atom);
 
 /**
  * Increment atomic uint64 variable
- * @note Relaxed memory order, cannot be used for synchronization
  *
- * @param[in,out] atom Pointer to an atomic uint64 variable
+ * @param atom    Pointer to atomic variable
  */
 void odp_atomic_inc_u64(odp_atomic_u64_t *atom);
 
 /**
  * Fetch and decrement atomic uint64 variable
- * @note Relaxed memory order, cannot be used for synchronization
  *
- * @param[in,out] atom Pointer to an atomic uint64 variable
+ * @param atom    Pointer to atomic variable
  *
  * @return Value of the variable before the decrement
  */
@@ -238,9 +223,8 @@ uint64_t odp_atomic_fetch_dec_u64(odp_atomic_u64_t *atom);
 
 /**
  * Decrement atomic uint64 variable
- * @note Relaxed memory order, cannot be used for synchronization
  *
- * @param[in,out] atom Pointer to an atomic uint64 variable
+ * @param atom    Pointer to atomic variable
  */
 void odp_atomic_dec_u64(odp_atomic_u64_t *atom);