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