On 23 October 2015 at 03:00, Petri Savolainen <petri.savolai...@nokia.com>
wrote:
> Removed module synchronizer from doxygen documentation and
> introduced new modules for locks, atomics and barriers. Removed
> unnecessary group tagging from internal headers, which are not
> visible to doxygen anyway.
>
> Signed-off-by: Petri Savolainen <petri.savolai...@nokia.com>
>
As long as a bug is created to follow up with the reorganisation of the
tests to match the new modules
Reviewed-by: Mike Holmes <mike.hol...@linaro.org>
> ---
> include/odp/api/atomic.h | 2 +-
> include/odp/api/barrier.h | 4 ++--
> include/odp/api/rwlock.h | 19
> +++++++++++--------
> include/odp/api/rwlock_recursive.h | 17
> ++++++++++-------
> include/odp/api/spinlock.h | 11 ++++++++---
> include/odp/api/spinlock_recursive.h | 15 +++++++++------
> include/odp/api/sync.h | 2 +-
> include/odp/api/ticketlock.h | 16
> ++++++++++------
> platform/linux-generic/include/odp/atomic.h | 2 +-
> platform/linux-generic/include/odp/barrier.h | 8 --------
> .../linux-generic/include/odp/plat/atomic_types.h | 8 --------
> .../linux-generic/include/odp/plat/barrier_types.h | 8 --------
> .../include/odp/plat/rwlock_recursive_types.h | 13 +------------
> .../linux-generic/include/odp/plat/rwlock_types.h | 13 +------------
> .../include/odp/plat/spinlock_recursive_types.h | 13 +------------
> .../linux-generic/include/odp/plat/spinlock_types.h | 14 +-------------
> .../linux-generic/include/odp/plat/ticketlock_types.h | 13 +------------
> platform/linux-generic/include/odp/rwlock.h | 8 --------
> platform/linux-generic/include/odp/spinlock.h | 8 --------
> platform/linux-generic/include/odp/sync.h | 8 --------
> platform/linux-generic/include/odp/ticketlock.h | 9 ---------
> platform/linux-generic/include/odp_atomic_internal.h | 9 ---------
> 22 files changed, 58 insertions(+), 162 deletions(-)
>
> diff --git a/include/odp/api/atomic.h b/include/odp/api/atomic.h
> index ba5c354..8aacc9d 100644
> --- a/include/odp/api/atomic.h
> +++ b/include/odp/api/atomic.h
> @@ -18,7 +18,7 @@
> extern "C" {
> #endif
>
> -/** @addtogroup odp_synchronizers
> +/** @defgroup odp_atomic ODP ATOMIC
> * Atomic types and relaxed operations. These operations cannot be used
> for
> * synchronization.
> * @{
> diff --git a/include/odp/api/barrier.h b/include/odp/api/barrier.h
> index 28310ba..8ca2647 100644
> --- a/include/odp/api/barrier.h
> +++ b/include/odp/api/barrier.h
> @@ -18,8 +18,8 @@
> extern "C" {
> #endif
>
> -/** @addtogroup odp_synchronizers
> - * Synchronize threads.
> +/** @defgroup odp_barrier ODP BARRIER
> + * Thread excution and memory ordering barriers.
> * @{
> */
>
> diff --git a/include/odp/api/rwlock.h b/include/odp/api/rwlock.h
> index d730a70..54f426f 100644
> --- a/include/odp/api/rwlock.h
> +++ b/include/odp/api/rwlock.h
> @@ -17,18 +17,21 @@
> extern "C" {
> #endif
>
> -/** @defgroup odp_synchronizers ODP SYNCRONIZERS
> - * Operations on reader/writer locks.
> - * A reader/writer lock allows multiple simultaneous readers but only one
> - * writer at a time.
> - * A thread that wants write access will have to wait until there are no
> - * threads that want read access. This casues a risk for starvation.
> - * @{
> +/**
> + * @defgroup odp_locks ODP LOCKS
> + * @details
> + * <b> Reader / writer lock (odp_rwlock_t) </b>
> + *
> + * A reader/writer lock allows multiple simultaneous readers but only one
> + * writer at a time. A thread that wants write access will have to wait
> until
> + * there are no threads that want read access. This casues a risk for
> + * starvation.
> + * @{
> */
>
> /**
> * @typedef odp_rwlock_t
> - * ODP rwlock
> + * ODP reader/writer lock
> */
>
>
> diff --git a/include/odp/api/rwlock_recursive.h
> b/include/odp/api/rwlock_recursive.h
> index 4c7556a..10b2f79 100644
> --- a/include/odp/api/rwlock_recursive.h
> +++ b/include/odp/api/rwlock_recursive.h
> @@ -17,15 +17,12 @@
> extern "C" {
> #endif
>
> -/** @addtogroup odp_synchronizers
> - * Operations on recursive rwlocks.
> - * @{
> - */
> -
> /**
> - * @typedef odp_rwlock_recursive_t
> - * Recursive rwlock
> + * @addtogroup odp_locks
> + * @details
> + * <b> Recursive reader/writer lock (odp_rwlock_recursive_t) </b>
> *
> + * This is recursive version of the reader/writer lock.
> * A thread can read- or write-acquire a recursive read-write lock
> multiple
> * times without a deadlock. To release the lock, the thread must unlock
> it
> * the same number of times. Recursion is supported only for a pure
> series of
> @@ -38,6 +35,12 @@ extern "C" {
> *
> * ... but this is not supported.
> * * read_lock(); write_lock(); write_unlock(); read_unlock();
> + * @{
> + */
> +
> +/**
> + * @typedef odp_rwlock_recursive_t
> + * Recursive rwlock
> */
>
> /**
> diff --git a/include/odp/api/spinlock.h b/include/odp/api/spinlock.h
> index 9a5a929..154d025 100644
> --- a/include/odp/api/spinlock.h
> +++ b/include/odp/api/spinlock.h
> @@ -18,9 +18,14 @@
> extern "C" {
> #endif
>
> -/** @addtogroup odp_synchronizers
> - * Operations on spin locks.
> - * @{
> +/**
> + * @addtogroup odp_locks
> + * @details
> + * <b> Spin lock (odp_spinlock_t) </b>
> + *
> + * Spinlock simply re-tries to acquire the lock as long as takes to
> succeed.
> + * Spinlock is not fair since some threads may succeed more often than
> others.
> + * @{
> */
>
> /**
> diff --git a/include/odp/api/spinlock_recursive.h
> b/include/odp/api/spinlock_recursive.h
> index 46b6be7..d98f2bb 100644
> --- a/include/odp/api/spinlock_recursive.h
> +++ b/include/odp/api/spinlock_recursive.h
> @@ -17,17 +17,20 @@
> extern "C" {
> #endif
>
> -/** @addtogroup odp_synchronizers
> - * Operations on recursive spinlocks.
> - * @{
> +/**
> + * @addtogroup odp_locks
> + * @details
> + * <b> Recursive spin lock (odp_spinlock_recursive_t) </b>
> + *
> + * This is recursive version of the spin lock. A thread can acquire the
> lock
> + * multiple times without a deadlock. To release the lock, the thread must
> + * unlock it the same number of times.
> + * @{
> */
>
> /**
> * @typedef odp_spinlock_recursive_t
> * Recursive spinlock
> - *
> - * A thread can acquire the lock multiple times without a deadlock. To
> release
> - * the lock, the thread must unlock it the same number of times.
> */
>
> /**
> diff --git a/include/odp/api/sync.h b/include/odp/api/sync.h
> index b338a98..6477e74 100644
> --- a/include/odp/api/sync.h
> +++ b/include/odp/api/sync.h
> @@ -18,7 +18,7 @@
> extern "C" {
> #endif
>
> -/** @addtogroup odp_synchronizers
> +/** @addtogroup odp_barrier
> * @{
> */
>
> diff --git a/include/odp/api/ticketlock.h b/include/odp/api/ticketlock.h
> index e395ac4..3f0e3f5 100644
> --- a/include/odp/api/ticketlock.h
> +++ b/include/odp/api/ticketlock.h
> @@ -18,13 +18,17 @@
> extern "C" {
> #endif
>
> -/** @addtogroup odp_synchronizers
> - * Operations on ticket locks.
> +/**
> + * @addtogroup odp_locks
> + * @details
> + * <b> Ticket lock (odp_ticketlock_t) </b>
> + *
> * Acquiring a ticket lock happens in two phases. First the threads takes
> a
> - * ticket. Second it waits (spins) until it is its turn.
> - * Ticket locks are believed to be more fair than spin locks.
> - * Ticket locks shall not be used in the presence of preemption.
> - * @{
> + * ticket. Second it waits (spins) until it is its turn. Ticket locks are
> + * believed to be more fair than spin locks. Ticket locks shall not be
> used
> + * if a thread may be preempted, since other threads cannot acquire the
> lock
> + * while the thread in turn is stalled.
> + * @{
> */
>
> /**
> diff --git a/platform/linux-generic/include/odp/atomic.h
> b/platform/linux-generic/include/odp/atomic.h
> index e47a280..deb4039 100644
> --- a/platform/linux-generic/include/odp/atomic.h
> +++ b/platform/linux-generic/include/odp/atomic.h
> @@ -21,7 +21,7 @@ extern "C" {
> #include <odp/align.h>
> #include <odp/plat/atomic_types.h>
>
> -/** @ingroup odp_synchronizers
> +/** @ingroup odp_atomic
> * @{
> */
>
> diff --git a/platform/linux-generic/include/odp/barrier.h
> b/platform/linux-generic/include/odp/barrier.h
> index 7ea5a6b..42df859 100644
> --- a/platform/linux-generic/include/odp/barrier.h
> +++ b/platform/linux-generic/include/odp/barrier.h
> @@ -21,14 +21,6 @@ extern "C" {
> #include <odp/plat/shared_memory_types.h>
> #include <odp/plat/barrier_types.h>
>
> -/** @ingroup odp_synchronizers
> - * @{
> - */
> -
> -/**
> - * @}
> - */
> -
> #include <odp/api/barrier.h>
>
> #ifdef __cplusplus
> diff --git a/platform/linux-generic/include/odp/plat/atomic_types.h
> b/platform/linux-generic/include/odp/plat/atomic_types.h
> index 3cdcab8..0f6c353 100644
> --- a/platform/linux-generic/include/odp/plat/atomic_types.h
> +++ b/platform/linux-generic/include/odp/plat/atomic_types.h
> @@ -62,18 +62,10 @@ struct odp_atomic_u32_s {
> })
> #endif
>
> -/** @addtogroup odp_synchronizers
> - * @{
> - */
> -
> typedef struct odp_atomic_u64_s odp_atomic_u64_t;
>
> typedef struct odp_atomic_u32_s odp_atomic_u32_t;
>
> -/**
> - * @}
> - */
> -
> #ifdef __cplusplus
> }
> #endif
> diff --git a/platform/linux-generic/include/odp/plat/barrier_types.h
> b/platform/linux-generic/include/odp/plat/barrier_types.h
> index c8c978d..b8e1d97 100644
> --- a/platform/linux-generic/include/odp/plat/barrier_types.h
> +++ b/platform/linux-generic/include/odp/plat/barrier_types.h
> @@ -30,16 +30,8 @@ struct odp_barrier_s {
> odp_atomic_u32_t bar; /**< Barrier counter */
> };
>
> -/** @addtogroup odp_synchronizers
> - * @{
> - */
> -
> typedef struct odp_barrier_s odp_barrier_t;
>
> -/**
> - * @}
> - */
> -
> #ifdef __cplusplus
> }
> #endif
> diff --git
> a/platform/linux-generic/include/odp/plat/rwlock_recursive_types.h
> b/platform/linux-generic/include/odp/plat/rwlock_recursive_types.h
> index ee81872..d5bfb92 100644
> --- a/platform/linux-generic/include/odp/plat/rwlock_recursive_types.h
> +++ b/platform/linux-generic/include/odp/plat/rwlock_recursive_types.h
> @@ -21,10 +21,7 @@ extern "C" {
> #include <odp/std_types.h>
> #include <odp_config_internal.h>
>
> -/**
> - * @internal
> - * ODP recursive rwlock
> - */
> +/** @internal */
> struct odp_rwlock_recursive_s {
> odp_rwlock_t lock; /**< the lock */
> int wr_owner; /**< write owner thread */
> @@ -32,16 +29,8 @@ struct odp_rwlock_recursive_s {
> uint8_t rd_cnt[_ODP_INTERNAL_MAX_THREADS]; /**< read recursion
> count */
> };
>
> -/** @addtogroup odp_synchronizers
> - * @{
> - */
> -
> typedef struct odp_rwlock_recursive_s odp_rwlock_recursive_t;
>
> -/**
> - * @}
> - */
> -
> #ifdef __cplusplus
> }
> #endif
> diff --git a/platform/linux-generic/include/odp/plat/rwlock_types.h
> b/platform/linux-generic/include/odp/plat/rwlock_types.h
> index bd46e57..35d65de 100644
> --- a/platform/linux-generic/include/odp/plat/rwlock_types.h
> +++ b/platform/linux-generic/include/odp/plat/rwlock_types.h
> @@ -20,10 +20,7 @@ extern "C" {
>
> #include <odp/atomic.h>
>
> -/**
> - * @internal
> - * ODP rwlock
> - */
> +/** @internal */
> struct odp_rwlock_s {
> odp_atomic_u32_t cnt; /**< lock count
> 0 lock not taken
> @@ -31,16 +28,8 @@ struct odp_rwlock_s {
> >0 read lock(s) taken */
> };
>
> -/** @addtogroup odp_synchronizers
> - * @{
> - */
> -
> typedef struct odp_rwlock_s odp_rwlock_t;
>
> -/**
> - * @}
> - */
> -
> #ifdef __cplusplus
> }
> #endif
> diff --git
> a/platform/linux-generic/include/odp/plat/spinlock_recursive_types.h
> b/platform/linux-generic/include/odp/plat/spinlock_recursive_types.h
> index cae47a4..2809277 100644
> --- a/platform/linux-generic/include/odp/plat/spinlock_recursive_types.h
> +++ b/platform/linux-generic/include/odp/plat/spinlock_recursive_types.h
> @@ -20,26 +20,15 @@ extern "C" {
> #include <odp/spinlock.h>
> #include <odp/std_types.h>
>
> -/**
> - * @internal
> - * ODP recursive spinlock
> - */
> +/** @internal */
> struct odp_spinlock_recursive_s {
> odp_spinlock_t lock; /**< the lock */
> int owner; /**< thread owning the lock */
> uint32_t cnt; /**< recursion count */
> };
>
> -/** @addtogroup odp_synchronizers
> - * @{
> - */
> -
> typedef struct odp_spinlock_recursive_s odp_spinlock_recursive_t;
>
> -/**
> - * @}
> - */
> -
> #ifdef __cplusplus
> }
> #endif
> diff --git a/platform/linux-generic/include/odp/plat/spinlock_types.h
> b/platform/linux-generic/include/odp/plat/spinlock_types.h
> index 83d306b..3e0231d 100644
> --- a/platform/linux-generic/include/odp/plat/spinlock_types.h
> +++ b/platform/linux-generic/include/odp/plat/spinlock_types.h
> @@ -20,25 +20,13 @@ extern "C" {
>
> #include <odp/std_types.h>
>
> -/**
> - * @internal
> - * ODP spinlock
> - */
> +/** @internal */
> struct odp_spinlock_s {
> char lock; /**< lock flag, should match odp_atomic_flag_t */
> };
>
> -
> -/** @addtogroup odp_synchronizers
> - * @{
> - */
> -
> typedef struct odp_spinlock_s odp_spinlock_t;
>
> -/**
> - * @}
> - */
> -
> #ifdef __cplusplus
> }
> #endif
> diff --git a/platform/linux-generic/include/odp/plat/ticketlock_types.h
> b/platform/linux-generic/include/odp/plat/ticketlock_types.h
> index be93085..73f9705 100644
> --- a/platform/linux-generic/include/odp/plat/ticketlock_types.h
> +++ b/platform/linux-generic/include/odp/plat/ticketlock_types.h
> @@ -20,25 +20,14 @@ extern "C" {
>
> #include <odp/atomic.h>
>
> -/**
> - * @internal
> - * ODP ticketlock
> - */
> +/** @internal */
> struct odp_ticketlock_s {
> odp_atomic_u32_t next_ticket; /**< Next ticket */
> odp_atomic_u32_t cur_ticket; /**< Current ticket */
> };
>
> -/** @addtogroup odp_synchronizers
> - * @{
> - */
> -
> typedef struct odp_ticketlock_s odp_ticketlock_t;
>
> -/**
> - * @}
> - */
> -
> #ifdef __cplusplus
> }
> #endif
> diff --git a/platform/linux-generic/include/odp/rwlock.h
> b/platform/linux-generic/include/odp/rwlock.h
> index ca88ff7..f9d8f5f 100644
> --- a/platform/linux-generic/include/odp/rwlock.h
> +++ b/platform/linux-generic/include/odp/rwlock.h
> @@ -19,14 +19,6 @@ extern "C" {
>
> #include <odp/plat/rwlock_types.h>
>
> -/** @ingroup odp_synchronizers
> - * @{
> - */
> -
> -/**
> - * @}
> - */
> -
> #include <odp/api/rwlock.h>
>
> #ifdef __cplusplus
> diff --git a/platform/linux-generic/include/odp/spinlock.h
> b/platform/linux-generic/include/odp/spinlock.h
> index 7dbb1c4..046fcfa 100644
> --- a/platform/linux-generic/include/odp/spinlock.h
> +++ b/platform/linux-generic/include/odp/spinlock.h
> @@ -19,14 +19,6 @@ extern "C" {
>
> #include <odp/plat/spinlock_types.h>
>
> -/** @ingroup odp_synchronizers
> - * @{
> - */
> -
> -/**
> - * @}
> - */
> -
> #include <odp/api/spinlock.h>
>
> #ifdef __cplusplus
> diff --git a/platform/linux-generic/include/odp/sync.h
> b/platform/linux-generic/include/odp/sync.h
> index 8cdab21..bc73083 100644
> --- a/platform/linux-generic/include/odp/sync.h
> +++ b/platform/linux-generic/include/odp/sync.h
> @@ -17,14 +17,6 @@
> extern "C" {
> #endif
>
> -/** @ingroup odp_synchronizers
> - * @{
> - */
> -
> -/**
> - * @}
> - */
> -
> #include <odp/api/sync.h>
>
> #ifdef __cplusplus
> diff --git a/platform/linux-generic/include/odp/ticketlock.h
> b/platform/linux-generic/include/odp/ticketlock.h
> index 658e27f..d349151 100644
> --- a/platform/linux-generic/include/odp/ticketlock.h
> +++ b/platform/linux-generic/include/odp/ticketlock.h
> @@ -19,15 +19,6 @@ extern "C" {
>
> #include <odp/plat/ticketlock_types.h>
>
> -/** @ingroup odp_synchronizers
> - * Operations on ticket locks.
> - * @{
> - */
> -
> -/**
> - * @}
> - */
> -
> #include <odp/api/ticketlock.h>
>
> #ifdef __cplusplus
> diff --git a/platform/linux-generic/include/odp_atomic_internal.h
> b/platform/linux-generic/include/odp_atomic_internal.h
> index 06fc16b..ce62368 100644
> --- a/platform/linux-generic/include/odp_atomic_internal.h
> +++ b/platform/linux-generic/include/odp_atomic_internal.h
> @@ -25,11 +25,6 @@
> extern "C" {
> #endif
>
> -/** @addtogroup odp_synchronizers
> - * Atomic operations.
> - * @{
> - */
> -
> /**
> * Pointer atomic type
> */
> @@ -598,10 +593,6 @@ static inline void
> _odp_atomic_flag_clear(_odp_atomic_flag_t *flag)
> __atomic_clear(flag, __ATOMIC_RELEASE);
> }
>
> -/**
> - * @}
> - */
> -
> #ifdef __cplusplus
> }
> #endif
> --
> 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
