diff options
22 files changed, 58 insertions, 162 deletions
diff --git a/include/odp/api/atomic.h b/include/odp/api/atomic.h index ba5c354e2..8aacc9d62 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 28310ba34..8ca264727 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 d730a7014..54f426fe7 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 4c7556a88..10b2f79ba 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 9a5a9290a..154d0258a 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 46b6be762..d98f2bbb6 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 b338a98a8..6477e7475 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 e395ac4ca..3f0e3f556 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 e47a280bf..deb4039b3 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 7ea5a6b99..42df8595a 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 3cdcab8bd..0f6c353a1 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 c8c978dca..b8e1d97bb 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 ee818723a..d5bfb9254 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 bd46e5722..35d65decb 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 cae47a4b1..2809277bd 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 83d306b5b..3e0231d1d 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 be9308556..73f970542 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 ca88ff7db..f9d8f5fd4 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 7dbb1c4bf..046fcfada 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 8cdab21ef..bc7308301 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 658e27fe4..d3491519a 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 06fc16b1b..ce62368e1 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 |