On 23 October 2015 at 03:00, Petri Savolainen <petri.savolai...@nokia.com>
wrote:
> 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>
>
Reviewed-by: Mike Holmes <mike.hol...@linaro.org>
> ---
> 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
>
--
Mike Holmes
Technical Manager - Linaro Networking Group
Linaro.org <http://www.linaro.org/> *│ *Open source software for ARM SoCs
_______________________________________________
lng-odp mailing list
lng-odp@lists.linaro.org
https://lists.linaro.org/mailman/listinfo/lng-odp
