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>
---
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
