From c6bbb0213d8c54c85b8672616711e67ca930cdb7 Mon Sep 17 00:00:00 2001 From: ajesh Date: Tue, 17 Sep 2019 11:21:08 +0530 Subject: [PATCH] gpu: nvgpu: add Doxygen documentation for lock Add Doxygen documentation for lock unit. Jira NVGPU-2596 Change-Id: I5761b1bc1bedf000b0d417e4dfa740606c70fe6d Signed-off-by: ajesh Reviewed-on: https://git-master.nvidia.com/r/2199379 Reviewed-by: Automatic_Commit_Validation_User Reviewed-by: Philip Elcan GVS: Gerrit_Virtual_Submit Reviewed-by: Alex Waterman Reviewed-by: mobile promotions Tested-by: mobile promotions --- drivers/gpu/nvgpu/include/nvgpu/lock.h | 105 +++++++++++++++++++ drivers/gpu/nvgpu/include/nvgpu/posix/lock.h | 36 +++++++ 2 files changed, 141 insertions(+) diff --git a/drivers/gpu/nvgpu/include/nvgpu/lock.h b/drivers/gpu/nvgpu/include/nvgpu/lock.h index 089cd5d25..a76069146 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/lock.h +++ b/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 */ diff --git a/drivers/gpu/nvgpu/include/nvgpu/posix/lock.h b/drivers/gpu/nvgpu/include/nvgpu/posix/lock.h index a0a855949..76e8c14e5 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/posix/lock.h +++ b/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; };