api:odp_ticketlock.h: Update doxygen comments, renaming of function params

Signed-off-by: Ola Liljedahl <ola.liljedahl@linaro.org>
Reviewed-by: Bill Fischofer <bill.fischofer@linaro.org>
Reviewed-by: Mike Holmes <mike.holmes@linaro.org>
Signed-off-by: Maxim Uvarov <maxim.uvarov@linaro.org>

1 files changed, 25 insertions, 20 deletions

diff --git a/platform/linux-generic/include/api/odp_ticketlock.h b/platform/linux-generic/include/api/odp_ticketlock.h
index 619816ed5..93a66b7b9 100644
--- a/platform/linux-generic/include/api/odp_ticketlock.h
+++ b/platform/linux-generic/include/api/odp_ticketlock.h
@@ -23,11 +23,16 @@ extern "C" {
 #include <odp_atomic.h>
 
 /** @addtogroup odp_synchronizers
+ * Operations on ticket locks.
+ * 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.
  *  @{
  */
 
 /**
- * ODP ticketlock
+ * ODP ticket lock
  */
 typedef struct odp_ticketlock_t {
 	odp_atomic_u32_t  next_ticket; /**< @private Next ticket */
@@ -36,47 +41,47 @@ typedef struct odp_ticketlock_t {
 
 
 /**
- * Init ticketlock
+ * Initialize ticket lock.
  *
- * @param ticketlock  Ticketlock
+ * @param tklock Pointer to a ticket lock
  */
-void odp_ticketlock_init(odp_ticketlock_t *ticketlock);
+void odp_ticketlock_init(odp_ticketlock_t *tklock);
 
 
 /**
- * Lock ticketlock
+ * Acquire ticket lock.
  *
- * @param ticketlock  Ticketlock
+ * @param tklock Pointer to a ticket lock
  */
-void odp_ticketlock_lock(odp_ticketlock_t *ticketlock);
-
+void odp_ticketlock_lock(odp_ticketlock_t *tklock);
 
 /**
- * Try to lock ticketlock
+ * Try to acquire ticket lock.
  *
- * @param ticketlock  Ticketlock
+ * @param tklock Pointer to a ticket lock
  *
- * @return 1 if the lock was taken, otherwise 0.
+ * @retval 1 lock acquired
+ * @retval 0 lock not acquired
  */
-int odp_ticketlock_trylock(odp_ticketlock_t *ticketlock);
-
+int odp_ticketlock_trylock(odp_ticketlock_t *tklock);
 
 /**
- * Unlock ticketlock
+ * Release ticket lock.
  *
- * @param ticketlock  Ticketlock
+ * @param tklock Pointer to a ticket lock
  */
-void odp_ticketlock_unlock(odp_ticketlock_t *ticketlock);
+void odp_ticketlock_unlock(odp_ticketlock_t *tklock);
 
 
 /**
- * Test if ticketlock is locked
+ * Check if ticket lock is locked.
  *
- * @param ticketlock  Ticketlock
+ * @param tklock Pointer to a ticket lock
  *
- * @return 1 if the lock is locked, otherwise 0.
+ * @retval 1 the lock is busy (locked)
+ * @retval 0 the lock is available (unlocked)
  */
-int odp_ticketlock_is_locked(odp_ticketlock_t *ticketlock);
+int odp_ticketlock_is_locked(odp_ticketlock_t *tklock);
 
 /**
  * @}