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.savolai...@nokia.com>
---
include/odp/api/atomic.h | 112 ++++++++++++++++++++---------------------------
1 file changed, 48 insertions(+), 64 deletions(-)
diff --git a/include/odp/api/atomic.h b/include/odp/api/atomic.h
index 8aacc9d..97e8639 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);
--
2.6.2
_______________________________________________
lng-odp mailing list
lng-odp@lists.linaro.org
https://lists.linaro.org/mailman/listinfo/lng-odp
