nv-tegra-mirror/linux-nvgpu
1
0
Fork 0
mirror of git://nv-tegra.nvidia.com/linux-nvgpu.git synced 2025-12-25 11:04:51 +03:00
Code Issues Packages Projects Releases Wiki Activity

gpu: nvgpu: add Doxygen documentation for cond

Browse Source 
Add Doxygen documentation details for cond unit.

Jira NVGPU-2414

Change-Id: I7cd455499a6b703d9150f5dbdb80a4344c634775
Signed-off-by: ajesh <akv@nvidia.com>
Reviewed-on: https://git-master.nvidia.com/r/2200393
Reviewed-by: Automatic_Commit_Validation_User
GVS: Gerrit_Virtual_Submit
Reviewed-by: Vijayakumar Subbu <vsubbu@nvidia.com>
Reviewed-by: Sagar Kamble <skamble@nvidia.com>
Reviewed-by: mobile promotions <svcmobile_promotions@nvidia.com>
Tested-by: mobile promotions <svcmobile_promotions@nvidia.com>
This commit is contained in:
ajesh
2019-09-18 12:37:41 +05:30
committed by Alex Waterman
parent 43e9263bc2
commit e8d5ed7694
2 changed files with 138 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

65
drivers/gpu/nvgpu/include/nvgpu/cond.h
View File

@@ -37,67 +37,78 @@
struct nvgpu_cond;
/**
* nvgpu_cond_init - Initialize a condition variable
* @brief Initialize a condition variable.
*
* @cond - The condition variable to initialize
* @param cond [in] The condition variable to initialize.
*
* Initialize a condition variable before using it.
*
* @return If successful, this function returns 0. Otherwise, an error number
* is returned to indicate the error.
*/
int nvgpu_cond_init(struct nvgpu_cond *cond);
/**
* nvgpu_cond_signal - Signal a condition variable
* @brief Signal a condition variable.
*
* @cond - The condition variable to signal
* @param cond [in] The condition variable to signal.
*
* Wake up a waiter for a condition variable to check if its condition has been
* satisfied.
*
* The waiter is using an uninterruptible wait.
* This function is used to unblock a thread blocked on a condition variable.
* Wakes up at least one of the threads that are blocked on the specified
* condition variable \a cond.
*/
void nvgpu_cond_signal(struct nvgpu_cond *cond);
/**
* nvgpu_cond_signal_interruptible - Signal a condition variable
* @brief Signal a condition variable.
*
* @cond - The condition variable to signal
* @param cond [in] The condition variable to signal.
*
* Wake up a waiter for a condition variable to check if its condition has been
* satisfied.
*
* The waiter is using an interruptible wait.
* Wakes up at least one of the threads that are blocked on the specified
* condition variable \a cond. In posix implementation, the function provides
* the same functionality as #nvgpu_cond_signal, but this function is being
* provided to be congruent with kernel implementations having interruptible
* and uninterruptible waits.
*/
void nvgpu_cond_signal_interruptible(struct nvgpu_cond *cond);
/**
* nvgpu_cond_broadcast - Signal all waiters of a condition variable
* @brief Signal all waiters of a condition variable.
*
* @cond - The condition variable to signal
* @param cond [in] The condition variable to broadcast.
*
* Wake up all waiters for a condition variable to check if their conditions
* have been satisfied.
* This function is used to unblock threads blocked on a condition variable.
* Wakes up all the threads that are blocked on the specified condition variable
* \a cond.
*
* The waiters are using an uninterruptible wait.
* @return If successful, this function returns 0. Otherwise, an error number
* is returned to indicate the error.
*/
int nvgpu_cond_broadcast(struct nvgpu_cond *cond);
/**
* nvgpu_cond_broadcast_interruptible - Signal all waiters of a condition
* variable
* @brief Signal all waiters of a condition variable.
*
* @cond - The condition variable to signal
* @param cond [in] The condition variable to broadcast.
*
* Wake up all waiters for a condition variable to check if their conditions
* have been satisfied.
* This function is used to unblock threads blocked on a condition variable.
* Wakes up all the threads that are blocked on the specified condition variable
* \a cond. In Posix implementation this API is same as #nvgpu_cond_broadcast in
* functionality, but the API is provided to be congruent with implementations
* having interruptible and uninterruptible waits.
*
* The waiters are using an interruptible wait.
* @return If successful, this function returns 0. Otherwise, an error number
* is returned to indicate the error.
*/
int nvgpu_cond_broadcast_interruptible(struct nvgpu_cond *cond);
/**
* nvgpu_cond_destroy - Destroy a condition variable
* @brief Destroy a condition variable.
*
* @cond - The condition variable to destroy
* @param cond [in] The condition variable to destroy.
*
* Destroys the condition variable along with the associated attributes and
* mutex.
*/
void nvgpu_cond_destroy(struct nvgpu_cond *cond);

121
drivers/gpu/nvgpu/include/nvgpu/posix/cond.h
View File

@@ -27,12 +27,27 @@
#include <nvgpu/bug.h>
#include <nvgpu/lock.h>
/**
* Define value used to indicate a wait without timeout.
*/
#define NVGPU_COND_WAIT_TIMEOUT_MAX_MS ~0U
struct nvgpu_cond {
/**
* Indicates the initialization status of the condition variable.
*/
bool initialized;
/**
* Mutex associated with the condition variable.
*/
struct nvgpu_mutex mutex;
/**
* Underlying pthread condition variable.
*/
pthread_cond_t cond;
/**
* Attributes associated with the condition variable.
*/
pthread_condattr_t attr;
};
@@ -40,21 +55,75 @@ struct nvgpu_cond {
struct nvgpu_posix_fault_inj *nvgpu_cond_get_fault_injection(void);
#endif
/**
* @brief Timed wait for a condition variable.
*
* @param cond [in] Condition variable to wait.
* @param ms [in] Timeout to wait.
*
* Waits for a condition variable for the time duration passed as param \a ms.
*
* @return If successful, this function returns 0. Otherwise, an error number
* is returned to indicate the error.
*/
int nvgpu_cond_timedwait(struct nvgpu_cond *c, unsigned int *ms);
/**
* @brief Signal a condition variable.
*
* @param cond [in] Condition variable to signal.
*
* Wakes up a waiter for a condition variable to check if its condition has
* been satisfied. This API has to be used after explicitly locking the mutex
* associated with the condition variable.
*/
void nvgpu_cond_signal_locked(struct nvgpu_cond *cond);
/**
* @brief Signal all waiters of a condition variable.
*
* @param cond [in] Condition variable to broadcast.
*
* Wake up all waiters for a condition variable to check if their conditions
* have been satisfied. This API has to be used after explicitly locking the
* mutex associated with the condition variable.
*
* @return If successful a value of 0 shall be returned; otherwise, an error
* number to indicate the error is returned.
*/
int nvgpu_cond_broadcast_locked(struct nvgpu_cond *cond);
/**
* @brief Acquire the mutex associated with condition variable.
*
* @param cond [in] Condition variable for which the mutex has to be
* acquired.
*
* Acquires the mutex associated with the condition variable referenced
* by the param \a cond.
*/
void nvgpu_cond_lock(struct nvgpu_cond *cond);
/**
* @brief Release the mutex associated with condition variable.
*
* @param cond [in] Condition variable for which the mutex has to be
* released.
*
* Releases the mutex associated with the condition variable referenced
* by the param \a cond.
*/
void nvgpu_cond_unlock(struct nvgpu_cond *cond);
/**
* NVGPU_COND_WAIT_LOCKED - Wait for a condition to be true
* @brief Wait for a condition to be true.
*
* @cond - The condition variable to sleep on
* @condition - The condition that needs to be true
* @timeout_ms - Timeout in milliseconds, or 0 for infinite wait.
* This parameter must be a u32.
* @param cond [in] The condition variable to sleep on.
* @param condition [in] The condition that needs to be checked.
* @param timeout_ms [in] Timeout in milliseconds or 0 for infinite wait.
*
* Wait for a condition to become true. Returns -ETIMEOUT if
* Wait for a condition to become true. Differentiates between timed wait
* and infinite wait from the parameter \a timeout_ms. Returns -ETIMEOUT if
* the wait timed out with condition false.
*/
#define NVGPU_COND_WAIT_LOCKED(cond, condition, timeout_ms) \
@@ -69,15 +138,15 @@ void nvgpu_cond_unlock(struct nvgpu_cond *cond);
})
/**
* NVGPU_COND_WAIT - Wait for a condition to be true
* @brief Initiate a wait for a condition variable.
*
* @cond - The condition variable to sleep on
* @condition - The condition that needs to be true
* @timeout_ms - Timeout in milliseconds, or 0 for infinite wait.
* This parameter must be a u32.
* @param cond [in] The condition variable to sleep on.
* @param condition [in] The condition that needs to be true.
* @param timeout_ms [in] Timeout in milliseconds or 0 for infinite wait.
*
* Wait for a condition to become true. Returns -ETIMEOUT if
* the wait timed out with condition false.
* Wait for a condition to become true. Returns -ETIMEOUT if the wait timed out
* with condition false. Acquires the mutex associated with the condition
* variable before attempting to wait.
*/
#define NVGPU_COND_WAIT(cond, condition, timeout_ms) \
({ \
@@ -94,20 +163,30 @@ void nvgpu_cond_unlock(struct nvgpu_cond *cond);
})
/**
* NVGPU_COND_WAIT_INTERRUPTIBLE - Wait for a condition to be true
* @brief Interruptible wait for a condition to be true.
*
* @cond - The condition variable to sleep on
* @condition - The condition that needs to be true
* @timeout_ms - Timeout in milliseconds, or 0 for infinite wait
* @param cond [in] The condition variable to sleep on.
* @param condition [in] The condition that needs to be true.
* @param timeout_ms [in] Timeout in milliseconds or 0 for infinite wait.
*
* Wait for a condition to become true. Returns -ETIMEOUT if
* the wait timed out with condition false or -ERESTARTSYS on
* signal.
* In posix implementation the functionality of interruptible wait is same as
* uninterruptible wait. Macro is defined to be congruent with implementations
* which has interruptible and uninterruptible waits.
*/
#define NVGPU_COND_WAIT_INTERRUPTIBLE(cond, condition, timeout_ms) \
NVGPU_COND_WAIT((cond), (condition), (timeout_ms))
/**
* @brief Wait for a condition to be true.
*
* @param cond [in] The condition variable to sleep on.
* @param condition [in] The condition that needs to be true.
* @param ret [out] Return value.
* @param timeout_ms [in] Timeout in milliseconds or 0 for infinite wait.
*
* Wait for a condition to become true. Returns -ETIMEOUT if the wait timed out
* with condition false.
*/
#define NVGPU_COND_WAIT_TIMEOUT_LOCKED(cond, condition, ret, timeout_ms)\
do { \
unsigned int cond_wait_timeout_timeout = (timeout_ms); \