gpu: nvgpu: add Doxygen documentation for lock

Add Doxygen documentation for lock unit.

Jira NVGPU-2596

Change-Id: I5761b1bc1bedf000b0d417e4dfa740606c70fe6d
Signed-off-by: ajesh <akv@nvidia.com>
Reviewed-on: https://git-master.nvidia.com/r/2199379
Reviewed-by: Automatic_Commit_Validation_User
Reviewed-by: Philip Elcan <pelcan@nvidia.com>
GVS: Gerrit_Virtual_Submit
Reviewed-by: Alex Waterman <alexw@nvidia.com>
Reviewed-by: mobile promotions <svcmobile_promotions@nvidia.com>
Tested-by: mobile promotions <svcmobile_promotions@nvidia.com>

drivers/gpu/nvgpu/include/nvgpu/lock.h

@@ -56,18 +56,123 @@ struct nvgpu_spinlock;
  */
 struct nvgpu_raw_spinlock;
 
+/**
+ * @brief Initialize the mutex object.
+ *
+ * @param mutex [in]	Mutex to initialize.
+ *
+ * Initialize the mutex object. Assert if the initialization returns error.
+ */
 void nvgpu_mutex_init(struct nvgpu_mutex *mutex);
+
+/**
+ * @brief Acquire the mutex object.
+ *
+ * @param mutex [in]	Mutex to acquire.
+ *
+ * Function locks the mutex object. If the mutex is already locked, then the
+ * calling thread blocks until it has acquired the mutex. When the function
+ * returns, the mutex object is locked and owned by the calling thread.
+ */
 void nvgpu_mutex_acquire(struct nvgpu_mutex *mutex);
+
+/**
+ * @brief Release the mutex object.
+ *
+ * @param mutex [in]	Mutex to release.
+ *
+ * Release the mutex object. The mutex object referenced by \a mutex will be
+ * unlocked. The mutex should be owned by the calling thread to unlock it.
+ */
 void nvgpu_mutex_release(struct nvgpu_mutex *mutex);
+
+/**
+ * @brief Attempt to lock the mutex object.
+ *
+ * @param mutex [in]	Mutex to try acquire.
+ *
+ * Attempts to lock the mutex object. If the mutex is already locked, this
+ * function returns an error code and hence the calling thread is not blocked.
+ *
+ * @return Return 1 if the mutex is successfully acquired, else return 0.
+ */
 int nvgpu_mutex_tryacquire(struct nvgpu_mutex *mutex);
+
+/**
+ * @brief Destroy the mutex object.
+ *
+ * @param mutex [in]	Mutex to destroy.
+ *
+ * The function shall destroy the mutex object referenced by \a mutex. The
+ * mutex object becomes uninitialized in effect.
+ */
 void nvgpu_mutex_destroy(struct nvgpu_mutex *mutex);
 
+/**
+ * @brief Initialize the spinlock object.
+ *
+ * @param spinlock [in]	Spinlock to initialize.
+ *
+ * Initialize the spinlock object. Underlying implementation and behaviour is
+ * dependent on the OS. Posix implementation internally uses mutex to support
+ * spinlock APIs. There is no reason to have a real spinlock implementation in
+ * userspace as the contexts which use the spinlock APIs are permitted to sleep
+ * in userspace execution mode, Hence all the spinlock APIs internally uses
+ * mutex logic in Posix implementation.
+ */
 void nvgpu_spinlock_init(struct nvgpu_spinlock *spinlock);
+
+/**
+ * @brief Acquire the spinlock object.
+ *
+ * @param spinlock [in]	Spinlock to acquire.
+ *
+ * Acquire the spinlock object. Underlying implementation and behaviour is
+ * dependent on the OS. Since pthread mutex is used internally for posix
+ * implementation, this function might put the calling thread in sleep state
+ * if the lock is not available.
+ */
 void nvgpu_spinlock_acquire(struct nvgpu_spinlock *spinlock);
+
+/**
+ * @brief Release the spinlock object.
+ *
+ * @param spinlock [in]	Spinlock to release.
+ *
+ * Releases the spinlock object referenced by \a spinlock.
+ */
 void nvgpu_spinlock_release(struct nvgpu_spinlock *spinlock);
 
+/**
+ * @brief Initialize the raw spinlock object.
+ *
+ * @param spinlock [in]	Raw spinlock structure to initialize.
+ *
+ * Initialize the raw spinlock object. Underlying implementation and behaviour
+ * is dependent on the OS. Posix implementation internally uses mutex to support
+ * raw spinlock APIs.
+ */
 void nvgpu_raw_spinlock_init(struct nvgpu_raw_spinlock *spinlock);
+
+/**
+ * @brief Acquire the raw spinlock object.
+ *
+ * @param spinlock [in]	Raw spinlock to acquire.
+ *
+ * Acquire the raw spinlock object. Underlying implementation and behaviour is
+ * dependent on the OS. Since pthread mutex is used internally for posix
+ * implementation, this function might put the calling thread in sleep state if
+ * the lock is not available.
+ */
 void nvgpu_raw_spinlock_acquire(struct nvgpu_raw_spinlock *spinlock);
+
+/**
+ * @brief Release the raw spinlock object.
+ *
+ * @param spinlock [in]	Raw spinlock to release.
+ *
+ * Release the raw spinlock object.
+ */
 void nvgpu_raw_spinlock_release(struct nvgpu_raw_spinlock *spinlock);
 
 #endif /* NVGPU_LOCK_H */

drivers/gpu/nvgpu/include/nvgpu/posix/lock.h

@@ -35,34 +35,70 @@
  * This could be revisited later, though.
  */
 struct __nvgpu_posix_lock {
+	/** Pthread mutex structure used internally to implement lock */
 	pthread_mutex_t mutex;
 };
 
+/**
+ * @brief Acquire the lock.
+ *
+ * @param lock [in]	Lock to acquire.
+ *
+ * Internal implementation of lock acquire used by public APIs of mutex,
+ * spinlock and raw spinlock. Uses pthread_mutex_lock to acquire the lock.
+ */
 static inline void nvgpu_posix_lock_acquire(struct __nvgpu_posix_lock *lock)
 {
 	(void) pthread_mutex_lock(&lock->mutex);
 }
 
+/**
+ * @brief Attempt to acquire the lock.
+ *
+ * @param lock [in]	Lock to acquire.
+ *
+ * Internal implementation of lock try and acquire used by public mutex APIs.
+ * Uses pthread_mutex_trylock to try and acquire the lock.
+ *
+ * @return Returns 0 on success; otherwise, returns error number.
+ */
 static inline int nvgpu_posix_lock_try_acquire(
 	struct __nvgpu_posix_lock *lock)
 {
 	return pthread_mutex_trylock(&lock->mutex);
 }
 
+/**
+ * @brief Release the lock.
+ *
+ * @param lock [in]	Lock to release.
+ *
+ * Internal implementation of lock release used by public APIs of mutex,
+ * spinlock and raw spinlock. Uses pthread_mutex_unlock to release the lock.
+ */
 static inline void nvgpu_posix_lock_release(struct __nvgpu_posix_lock *lock)
 {
 	(void) pthread_mutex_unlock(&lock->mutex);
 }
 
 struct nvgpu_mutex {
+	/**
+	 * nvgpu lock structure used to implement mutex APIs.
+	 */
 	struct __nvgpu_posix_lock lock;
 };
 
 struct nvgpu_spinlock {
+	/**
+	 * nvgpu lock structure used to implement spinlock APIs.
+	 */
 	struct __nvgpu_posix_lock lock;
 };
 
 struct nvgpu_raw_spinlock {
+	/**
+	 * nvgpu lock structure used to implement raw spinlock APIs.
+	 */
 	struct __nvgpu_posix_lock lock;
 };