diff --git a/drivers/gpu/nvgpu/include/nvgpu/atomic.h b/drivers/gpu/nvgpu/include/nvgpu/atomic.h index c130faca2..c8d20cece 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/atomic.h +++ b/drivers/gpu/nvgpu/include/nvgpu/atomic.h @@ -1,5 +1,5 @@ /* - * Copyright (c) 2017-2020, NVIDIA CORPORATION. All rights reserved. + * Copyright (c) 2017-2021, NVIDIA CORPORATION. All rights reserved. * * Permission is hereby granted, free of charge, to any person obtaining a * copy of this software and associated documentation files (the "Software"), @@ -36,10 +36,10 @@ /** * @brief Set atomic variable. * + * Sets the value \a i atomically in structure \a v. + * * @param v [in] Structure holding atomic variable. * @param i [in] Value to set. - * - * Sets the value \a i atomically in structure \a v. */ static inline void nvgpu_atomic_set(nvgpu_atomic_t *v, int i) { @@ -49,10 +49,10 @@ static inline void nvgpu_atomic_set(nvgpu_atomic_t *v, int i) /** * @brief Read atomic variable. * - * @param v [in] Structure holding atomic variable to read. - * * Atomically reads the value from structure \a v. * + * @param v [in] Structure holding atomic variable to read. + * * @return Value read from the atomic variable. */ static inline int nvgpu_atomic_read(nvgpu_atomic_t *v) @@ -63,9 +63,9 @@ static inline int nvgpu_atomic_read(nvgpu_atomic_t *v) /** * @brief Increment the atomic variable. * - * @param v [in] Structure holding atomic variable. + * Atomically increments the value in structure \a v by 1. * - * Atomically increments the value in structure \a v. + * @param v [in] Structure holding atomic variable. */ static inline void nvgpu_atomic_inc(nvgpu_atomic_t *v) { @@ -75,9 +75,9 @@ static inline void nvgpu_atomic_inc(nvgpu_atomic_t *v) /** * @brief Increment the atomic variable and return. * - * @param v [in] Structure holding atomic variable. + * Atomically increases the value in structure \a v by 1 and returns. * - * Atomically increases the value in structure \a v and returns. + * @param v [in] Structure holding atomic variable. * * @return Value in atomic variable incremented by 1. */ @@ -89,9 +89,9 @@ static inline int nvgpu_atomic_inc_return(nvgpu_atomic_t *v) /** * @brief Decrement the atomic variable. * - * @param v [in] Structure holding atomic variable. + * Atomically decrements the value in structure \a v by 1. * - * Atomically decrements the value in structure \a v. + * @param v [in] Structure holding atomic variable. */ static inline void nvgpu_atomic_dec(nvgpu_atomic_t *v) { @@ -101,9 +101,9 @@ static inline void nvgpu_atomic_dec(nvgpu_atomic_t *v) /** * @brief Decrement the atomic variable and return. * - * @param v [in] Structure holding atomic variable. + * Atomically decrements the value in structure \a v by 1 and returns. * - * Atomically decrements the value in structure v and returns. + * @param v [in] Structure holding atomic variable. * * @return Value in atomic variable decremented by 1. */ @@ -115,14 +115,14 @@ static inline int nvgpu_atomic_dec_return(nvgpu_atomic_t *v) /** * @brief Compare and exchange the value in atomic variable. * - * @param v [in] Structure holding atomic variable. - * @param old [in] Value to compare. - * @param new [in] Value to store. - * * Reads the value stored in \a v, replace the value with \a new if the read * value is equal to \a old. In cases where the current value in \a v is not * equal to \a old, this function acts as a read operation of atomic variable. * + * @param v [in] Structure holding atomic variable. + * @param old [in] Value to compare. + * @param new [in] Value to store. + * * @return Reads the value in \a v before the exchange operation and returns. * Read value is returned irrespective of whether the exchange operation is * carried out or not. @@ -135,11 +135,11 @@ static inline int nvgpu_atomic_cmpxchg(nvgpu_atomic_t *v, int old, int new) /** * @brief Exchange the value in atomic variable. * + * Atomically exchanges the value stored in \a v with \a new. + * * @param v [in] Structure holding atomic variable. * @param new [in] Value to set. * - * Atomically exchanges the value stored in \a v with \a new. - * * @return Value in atomic variable before the operation. */ static inline int nvgpu_atomic_xchg(nvgpu_atomic_t *v, int new) @@ -150,10 +150,10 @@ static inline int nvgpu_atomic_xchg(nvgpu_atomic_t *v, int new) /** * @brief Increment the atomic variable and test for zero. * - * @param v [in] Structure holding atomic variable. + * Atomically increments the value stored in \a v by 1 and compare the result + * with zero. * - * Atomically increments the value stored in \a v and compare the result with - * zero. + * @param v [in] Structure holding atomic variable. * * @return Boolean value indicating the status of comparison operation done * after incrementing the atomic variable. @@ -169,10 +169,10 @@ static inline bool nvgpu_atomic_inc_and_test(nvgpu_atomic_t *v) /** * @brief Decrement the atomic variable and test for zero. * - * @param v [in] Structure holding atomic variable. + * Atomically decrements the value stored in \a v by 1 and compare the result + * with zero. * - * Atomically decrements the value stored in \a v and compare the result with - * zero. + * @param v [in] Structure holding atomic variable. * * @return Boolean value indicating the status of comparison operation done * after decrementing the atomic variable. @@ -188,12 +188,12 @@ static inline bool nvgpu_atomic_dec_and_test(nvgpu_atomic_t *v) /** * @brief Subtract integer from atomic variable and test. * - * @param i [in] Value to subtract. - * @param v [in] Structure holding atomic variable. - * * Atomically subtracts \a i from the value stored in \a v and compare the * result with zero. * + * @param i [in] Value to subtract. + * @param v [in] Structure holding atomic variable. + * * @return Boolean value indicating the status of comparison operation done * after the subtraction operation on atomic variable. * @@ -208,10 +208,10 @@ static inline bool nvgpu_atomic_sub_and_test(int i, nvgpu_atomic_t *v) /** * @brief Add integer to atomic variable. * + * Atomically adds \a i to the value stored in structure \a v. + * * @param i [in] Value to add. * @param v [in] Structure holding atomic variable. - * - * Atomically adds \a i to the value stored in structure \a v. */ static inline void nvgpu_atomic_add(int i, nvgpu_atomic_t *v) { @@ -221,12 +221,12 @@ static inline void nvgpu_atomic_add(int i, nvgpu_atomic_t *v) /** * @brief Subtract integer form atomic variable and return. * - * @param i [in] Value to subtract. - * @param v [in] Structure holding atomic variable. - * * Atomically subtracts \a i from the value stored in structure \a v and * returns. * + * @param i [in] Value to subtract. + * @param v [in] Structure holding atomic variable. + * * @return \a i subtracted from \a v is returned. */ static inline int nvgpu_atomic_sub_return(int i, nvgpu_atomic_t *v) @@ -237,10 +237,10 @@ static inline int nvgpu_atomic_sub_return(int i, nvgpu_atomic_t *v) /** * @brief Subtract integer from atomic variable. * + * Atomically subtracts \a i from the value stored in structure \a v. + * * @param i [in] Value to set. * @param v [in] Structure holding atomic variable. - * - * Atomically subtracts \a i from the value stored in structure \a v. */ static inline void nvgpu_atomic_sub(int i, nvgpu_atomic_t *v) { @@ -250,11 +250,11 @@ static inline void nvgpu_atomic_sub(int i, nvgpu_atomic_t *v) /** * @brief Add integer to atomic variable and return. * + * Atomically adds \a i to the value in structure \a v and returns. + * * @param i [in] Value to add. * @param v [in] Structure holding atomic variable. * - * Atomically adds \a i to the value in structure \a v and returns. - * * @return Current value in \a v added with \a i is returned. */ static inline int nvgpu_atomic_add_return(int i, nvgpu_atomic_t *v) @@ -265,12 +265,12 @@ static inline int nvgpu_atomic_add_return(int i, nvgpu_atomic_t *v) /** * @brief Add integer to atomic variable on unless condition. * + * Atomically adds \a a to \a v if \a v is not \a u. + * * @param v [in] Structure holding atomic variable. * @param a [in] Value to add. * @param u [in] Value to check. * - * Atomically adds \a a to \a v if \a v is not \a u. - * * @return Value in the atomic variable before the operation. */ static inline int nvgpu_atomic_add_unless(nvgpu_atomic_t *v, int a, int u) @@ -281,10 +281,10 @@ static inline int nvgpu_atomic_add_unless(nvgpu_atomic_t *v, int a, int u) /** * @brief Set the 64 bit atomic variable. * - * @param v [in] Structure holding atomic variable. - * @param i [in] Value to set. + * Atomically sets the 64 bit value \a x in structure \a v. * - * Atomically sets the 64 bit value \a i in structure \a v. + * @param v [in] Structure holding atomic variable. + * @param x [in] Value to set. */ static inline void nvgpu_atomic64_set(nvgpu_atomic64_t *v, long x) { @@ -294,10 +294,10 @@ static inline void nvgpu_atomic64_set(nvgpu_atomic64_t *v, long x) /** * @brief Read the 64 bit atomic variable. * - * @param v [in] Structure holding atomic variable. - * * Atomically reads the 64 bit value in structure \a v. * + * @param v [in] Structure holding atomic variable. + * * @return Value read from the atomic variable. */ static inline long nvgpu_atomic64_read(nvgpu_atomic64_t *v) @@ -308,10 +308,10 @@ static inline long nvgpu_atomic64_read(nvgpu_atomic64_t *v) /** * @brief Addition of 64 bit integer to atomic variable. * + * Atomically adds the 64 bit value \a x to \a v. + * * @param x [in] Value to add. * @param v [in] Structure holding atomic variable. - * - * Atomically adds the 64 bit value \a x to \a v. */ static inline void nvgpu_atomic64_add(long x, nvgpu_atomic64_t *v) { @@ -321,9 +321,9 @@ static inline void nvgpu_atomic64_add(long x, nvgpu_atomic64_t *v) /** * @brief Increment the 64 bit atomic variable. * - * @param v [in] Structure holding atomic variable. + * Atomically increments the value in structure \a v by 1. * - * Atomically increments the value in structure \a v. + * @param v [in] Structure holding atomic variable. */ static inline void nvgpu_atomic64_inc(nvgpu_atomic64_t *v) { @@ -333,9 +333,9 @@ static inline void nvgpu_atomic64_inc(nvgpu_atomic64_t *v) /** * @brief Increment the 64 bit atomic variable and return. * - * @param v [in] Structure holding atomic variable. + * Atomically increments the value in structure \a v by 1 and returns. * - * Atomically increments the value in structure \a v and returns. + * @param v [in] Structure holding atomic variable. * * @return Value in atomic variable incremented by 1. */ @@ -347,9 +347,9 @@ static inline long nvgpu_atomic64_inc_return(nvgpu_atomic64_t *v) /** * @brief Decrement the 64 bit atomic variable. * - * @param v [in] Structure holding atomic variable. + * Atomically decrements the value in structure \a v by 1. * - * Atomically decrements the value in structure \a v. + * @param v [in] Structure holding atomic variable. */ static inline void nvgpu_atomic64_dec(nvgpu_atomic64_t *v) { @@ -359,9 +359,9 @@ static inline void nvgpu_atomic64_dec(nvgpu_atomic64_t *v) /** * @brief Decrement the 64 bit atomic variable and return. * - * @param v [in] Structure holding atomic variable. + * Atomically decrements the value in structure \a v by 1 and returns. * - * Atomically decrements the value in structure \a v and returns. + * @param v [in] Structure holding atomic variable. * * @return Value in atomic variable decremented by 1. */ @@ -373,11 +373,11 @@ static inline long nvgpu_atomic64_dec_return(nvgpu_atomic64_t *v) /** * @brief Exchange the 64 bit atomic variable value. * + * Atomically exchanges the value \a new with the value in \a v. + * * @param v [in] Structure holding atomic variable. * @param new [in] Value to set. * - * Atomically exchanges the value \a new with the value in \a v. - * * @return Value in the atomic variable before the exchange operation. */ static inline long nvgpu_atomic64_xchg(nvgpu_atomic64_t *v, long new) @@ -388,14 +388,14 @@ static inline long nvgpu_atomic64_xchg(nvgpu_atomic64_t *v, long new) /** * @brief Compare and exchange the 64 bit atomic variable value. * - * @param v [in] Structure holding atomic variable. - * @param old [in] Value to compare. - * @param new [in] Value to exchange. - * Reads the value stored in \a v, replace the value with \a new if the read * value is equal to \a old. In cases where the current value in \a v is not * equal to \a old, this function acts as a read operation of atomic variable. * + * @param v [in] Structure holding atomic variable. + * @param old [in] Value to compare. + * @param new [in] Value to exchange. + * * @return Returns the original value in atomic variable. */ static inline long nvgpu_atomic64_cmpxchg(nvgpu_atomic64_t *v, long old, @@ -407,11 +407,11 @@ static inline long nvgpu_atomic64_cmpxchg(nvgpu_atomic64_t *v, long old, /** * @brief Addition of 64 bit integer to atomic variable and return. * + * Atomically add the value \a x with \a v and returns. + * * @param x [in] Value to add. * @param v [in] Structure holding atomic variable. * - * Atomically add the value x with v and returns. - * * @return Current value in atomic variable added with \a x. */ static inline long nvgpu_atomic64_add_return(long x, nvgpu_atomic64_t *v) @@ -422,12 +422,12 @@ static inline long nvgpu_atomic64_add_return(long x, nvgpu_atomic64_t *v) /** * @brief Addition of 64 bit atomic variable on unless condition. * + * Atomically adds 64 bit value \a a to \a v if \a v is not \a u. + * * @param v [in] Structure holding atomic variable. * @param a [in] Value to add. * @param u [in] Value to check. * - * Atomically adds 64 bit value \a a to \a v if \a v is not \a u. - * * @return Value in atomic variable before the operation. */ static inline long nvgpu_atomic64_add_unless(nvgpu_atomic64_t *v, long a, @@ -439,10 +439,10 @@ static inline long nvgpu_atomic64_add_unless(nvgpu_atomic64_t *v, long a, /** * @brief Subtraction of 64 bit integer from atomic variable. * + * Atomically subtracts the 64 bit value \a x from structure \a v. + * * @param x [in] Value to subtract. * @param v [in] Structure holding atomic variable. - * - * Atomically subtracts the 64 bit value \a x from structure \a v. */ static inline void nvgpu_atomic64_sub(long x, nvgpu_atomic64_t *v) { @@ -452,11 +452,11 @@ static inline void nvgpu_atomic64_sub(long x, nvgpu_atomic64_t *v) /** * @brief Increment the 64 bit atomic variable and test. * - * @param v [in] Structure holding atomic variable. - * * Atomically increments the value stored in \a v and compare the result with * zero. * + * @param v [in] Structure holding atomic variable. + * * @return Boolean value indicating the status of comparison operation done * after incrementing the atomic variable. * @@ -471,11 +471,11 @@ static inline bool nvgpu_atomic64_inc_and_test(nvgpu_atomic64_t *v) /** * @brief Decrement the 64 bit atomic variable and test. * - * @param v [in] Structure holding atomic variable. - * * Atomically decrements the value stored in \a v and compare the result with * zero. * + * @param v [in] Structure holding atomic variable. + * * @return Boolean value indicating the status of comparison operation done * after decrementing the atomic variable. * @@ -490,11 +490,11 @@ static inline bool nvgpu_atomic64_dec_and_test(nvgpu_atomic64_t *v) /** * @brief Subtract 64 bit integer from atomic variable and test. * + * Atomically subtracts \a x from \a v and compare the result with zero. + * * @param x [in] Value to subtract. * @param v [in] Structure holding atomic variable. * - * Atomically subtracts \a x from \a v and compare the result with zero. - * * @return Boolean value indicating the status of comparison operation done * after the subtraction operation on atomic variable. * @@ -509,11 +509,11 @@ static inline bool nvgpu_atomic64_sub_and_test(long x, nvgpu_atomic64_t *v) /** * @brief Subtract 64 bit integer from atomic variable and return. * + * Atomically subtracts \a x from \a v and returns. + * * @param x [in] Value to subtract. * @param v [in] Structure holding atomic variable. * - * Atomically subtracts \a x from \a v and returns. - * * @return \a x subtracted from the current value in atomic variable. */ static inline long nvgpu_atomic64_sub_return(long x, nvgpu_atomic64_t *v) diff --git a/drivers/gpu/nvgpu/include/nvgpu/cond.h b/drivers/gpu/nvgpu/include/nvgpu/cond.h index 6629ffc7f..e3151428b 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/cond.h +++ b/drivers/gpu/nvgpu/include/nvgpu/cond.h @@ -58,45 +58,45 @@ int nvgpu_cond_init(struct nvgpu_cond *cond); /** * @brief Signal a condition variable. * + * 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. + * * @param cond [in] The condition variable to signal. * - Should not to be equal to NULL. * - Structure pointed by \a cond should be initialized * before invoking this function. - * - * 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); /** * @brief Signal a condition variable. * - * @param cond [in] The condition variable to signal. - * - Should not to be equal to NULL. - * - Structure pointed by \a cond should be initialized - * before invoking this function. - * * 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. + * + * @param cond [in] The condition variable to signal. + * - Should not to be equal to NULL. + * - Structure pointed by \a cond should be initialized + * before invoking this function. */ void nvgpu_cond_signal_interruptible(struct nvgpu_cond *cond); /** * @brief Signal all waiters of a condition variable. * + * 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. + * * @param cond [in] The condition variable to broadcast. * - Should not to be equal to NULL. * - Structure pointed by \a cond should be initialized * before invoking this function. * - * 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. - * * @return If successful, this function returns 0. Otherwise, an error number * is returned to indicate the error. * @@ -110,17 +110,17 @@ int nvgpu_cond_broadcast(struct nvgpu_cond *cond); /** * @brief Signal all waiters of a condition variable. * - * @param cond [in] The condition variable to broadcast. - * - Should not to be equal to NULL. - * - Structure pointed by \a cond should be initialized - * before invoking this function. - * * 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. * + * @param cond [in] The condition variable to broadcast. + * - Should not to be equal to NULL. + * - Structure pointed by \a cond should be initialized + * before invoking this function. + * * @return If successful, this function returns 0. Otherwise, an error number * is returned to indicate the error. * @@ -134,11 +134,11 @@ int nvgpu_cond_broadcast_interruptible(struct nvgpu_cond *cond); /** * @brief Destroy a condition variable. * - * @param cond [in] The condition variable to destroy. - * - Should not to be equal to NULL. - * * Destroys the condition variable along with the associated attributes and * mutex. + * + * @param cond [in] The condition variable to destroy. + * - Should not to be equal to NULL. */ void nvgpu_cond_destroy(struct nvgpu_cond *cond); diff --git a/drivers/gpu/nvgpu/include/nvgpu/kmem.h b/drivers/gpu/nvgpu/include/nvgpu/kmem.h index d99345491..d811d6ddb 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/kmem.h +++ b/drivers/gpu/nvgpu/include/nvgpu/kmem.h @@ -1,5 +1,5 @@ /* - * Copyright (c) 2017-2020, NVIDIA CORPORATION. All rights reserved. + * Copyright (c) 2017-2021, NVIDIA CORPORATION. All rights reserved. * * Permission is hereby granted, free of charge, to any person obtaining a * copy of this software and associated documentation files (the "Software"), @@ -77,17 +77,20 @@ struct nvgpu_mem_alloc_tracker; /** * @brief Create an nvgpu memory cache. * + * The internal implementation of the function is OS specific. In Posix + * implementation, the function would just allocate a normal malloc memory for + * the cache structure and stores the value of \a size inside the structure. + * This cache can be used to allocate objects of size \a size. Common usage + * would be for a struct that gets allocated a lot. In that case \a size + * should be sizeof(struct my_struct). A given implementation of this need not + * do anything special. The allocation routines can simply be passed on to + * nvgpu_kzalloc() if desired, so packing and alignment of the structs cannot + * be assumed. In Posix implementation, the allocation from this cache would + * just return a normal malloc memory of size \a size. + * * @param g [in] The GPU driver struct using this cache. * @param size [in] Size of the object allocated by the cache. * - * This cache can be used to allocate objects of size #size. Common usage would - * be for a struct that gets allocated a lot. In that case #size should be - * sizeof(struct my_struct). - * - * A given implementation of this need not do anything special. The allocation - * routines can simply be passed on to nvgpu_kzalloc() if desired so packing - * and alignment of the structs cannot be assumed. - * * @return Pointer to #nvgpu_kmem_cache in case of success, else NULL. * * @retval NULL in case of failure. @@ -97,18 +100,20 @@ struct nvgpu_kmem_cache *nvgpu_kmem_cache_create(struct gk20a *g, size_t size); /** * @brief Destroy a cache created by #nvgpu_kmem_cache_create(). * - * @param cache [in] The cache to destroy. - * * Destroy the allocated OS specific internal structure to avoid the memleak. + * + * @param cache [in] The cache to destroy. */ void nvgpu_kmem_cache_destroy(struct nvgpu_kmem_cache *cache); /** * @brief Allocate an object from the cache * - * @param cache [in] The cache to alloc from. - * * Allocate an object from a cache created using #nvgpu_kmem_cache_create(). + * In Posix implementation, this function would just return a normal malloc + * memory. + * + * @param cache [in] The cache to alloc from. * * @return Pointer to an object in case of success, else NULL. * @@ -119,23 +124,22 @@ void *nvgpu_kmem_cache_alloc(struct nvgpu_kmem_cache *cache); /** * @brief Free an object back to a cache * + * Free an object back to a cache allocated using #nvgpu_kmem_cache_alloc(). + * * @param cache [in] The cache to return the object to. * @param ptr [in] Pointer to the object to free. - * - * Free an object back to a cache allocated using #nvgpu_kmem_cache_alloc(). */ void nvgpu_kmem_cache_free(struct nvgpu_kmem_cache *cache, void *ptr); /** * @brief Allocate from the OS allocator. * + * Allocate a chunk of system memory from the process address space. + * This function may sleep so cannot be used in IRQs. + * * @param g [in] Current GPU. * @param size [in] Size of the allocation. * - * Allocate a chunk of system memory from the process address space. - * - * This function may sleep so cannot be used in IRQs. - * * @return Pointer to an object in case of success, else NULL. * * @retval NULL in case of failure. @@ -145,12 +149,12 @@ void nvgpu_kmem_cache_free(struct nvgpu_kmem_cache *cache, void *ptr); /** * @brief Allocate from the OS allocator. * - * @param g [in] Current GPU. - * @param size [in] Size of the allocation. - * * Identical to nvgpu_kalloc() except the memory will be zeroed before being * returned. * + * @param g [in] Current GPU. + * @param size [in] Size of the allocation. + * * @return Pointer to an object in case of success, else NULL. * * @retval NULL in case of failure. @@ -160,13 +164,13 @@ void nvgpu_kmem_cache_free(struct nvgpu_kmem_cache *cache, void *ptr); /** * @brief Allocate from the OS allocator. * + * Identical to nvgpu_kalloc() except the size of the memory chunk returned is + * \a n * \a size. + * * @param g [in] Current GPU. * @param n [in] Number of objects. * @param size [in] Size of each object. * - * Identical to nvgpu_kalloc() except the size of the memory chunk returned is - * #n * #size. - * * @return Pointer to an object in case of success, else NULL. * * @retval NULL in case of failure. @@ -177,16 +181,14 @@ void nvgpu_kmem_cache_free(struct nvgpu_kmem_cache *cache, void *ptr); /** * @brief Allocate memory and return a map to it. * - * @param g [in] Current GPU. - * @param size [in] Size of the allocation. - * * Allocate some memory and return a pointer to a virtual memory mapping of * that memory (using malloc for Qnx). The underlying physical * memory is not guaranteed to be contiguous (and indeed likely isn't). This * allows for much larger allocations to be done without worrying about as much - * about physical memory fragmentation. + * about physical memory fragmentation. This function may sleep. * - * This function may sleep. + * @param g [in] Current GPU. + * @param size [in] Size of the allocation. * * @return Pointer to an object in case of success, else NULL. * @@ -197,11 +199,11 @@ void nvgpu_kmem_cache_free(struct nvgpu_kmem_cache *cache, void *ptr); /** * @brief Allocate memory and return a map to it. * + * Identical to nvgpu_vmalloc() except this will return zero'ed memory. + * * @param g [in] Current GPU. * @param size [in] Size of the allocation. * - * Identical to nvgpu_vmalloc() except this will return zero'ed memory. - * * @return Pointer to an object in case of success, else NULL. * * @retval NULL in case of failure. @@ -230,12 +232,11 @@ void nvgpu_kmem_cache_free(struct nvgpu_kmem_cache *cache, void *ptr); /** * @brief Initialize the kmem tracking stuff. * + * Initialize the kmem tracking internal structure. Internal implementation + * is specific to OS. + * * @param g [in] The driver to init. * - * Initialize the kmem tracking internal structure. - * - * Internal implementation is specific to OS. - * * @return 0 in case of success, non-zero in case of failure. Posix * implementation is a dummy function which just returns 0. * @@ -275,28 +276,18 @@ void nvgpu_kmem_fini(struct gk20a *g, int flags); #define NVGPU_KMEM_FINI_BUG (1 << 3) /** - * @brief Pick virtual or physical alloc based on @size + * @brief Wrapper for memory allocation functions. + * + * The internal implementation of this function is OS specific. For Posix + * implementation, the requested \a size of memory is allocated and returns + * a pointer to that memory. The parameter \a clear is used to decide if the + * allocated memory has to be zero filled or not. Based on \a clear value, + * calloc or malloc is used internally in Posix implementation. * * @param g [in] The GPU. * @param size [in] Size of the allocation. * @param clear [in] Flag indicates the need of zeroed memory. * - * On some platforms (i.e Linux) it is possible to allocate memory directly - * mapped into the kernel's address space (kmalloc) or allocate discontiguous - * pages which are then mapped into a special kernel address range. Each type - * of allocation has pros and cons. kmalloc() for instance lets you allocate - * small buffers more space efficiently but vmalloc() allows you to successfully - * allocate much larger buffers without worrying about fragmentation as much - * (but will allocate in multiples of page size). - * - * Allocate some memory and return a pointer to a virtual memory mapping of - * that memory (using malloc for Qnx). - * - * This function aims to provide the right allocation for when buffers are of - * variable size. In some cases the code doesn't know ahead of time if the - * buffer is going to be big or small so this does the check for you and - * provides the right type of memory allocation. - * * @return upon successful allocation a pointer to a virtual address range * that the nvgpu can access is returned, else NULL. * @@ -307,11 +298,11 @@ void *nvgpu_big_alloc_impl(struct gk20a *g, size_t size, bool clear); /** * @brief Pick virtual or physical alloc based on @size * + * It is wrapper around nvgpu_big_alloc_impl() + * * @param g [in] The GPU. * @param size [in] Size of the allocation. * - * It is wrapper around nvgpu_big_alloc_impl() - * * @return upon successful allocation a pointer to a virtual address range * that the nvgpu can access is returned, else NULL. * @@ -341,7 +332,7 @@ static inline void *nvgpu_big_zalloc(struct gk20a *g, size_t size) } /** - * @brief Free and alloc from nvgpu_big_zalloc() or nvgpu_big_malloc(). + * @brief Free any alloc from nvgpu_big_zalloc() or nvgpu_big_malloc(). * * @param g [in] The GPU. * @param p [in] A pointer allocated by nvgpu_big_zalloc() or nvgpu_big_malloc(). diff --git a/drivers/gpu/nvgpu/include/nvgpu/lock.h b/drivers/gpu/nvgpu/include/nvgpu/lock.h index 17e85e214..017c25f89 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/lock.h +++ b/drivers/gpu/nvgpu/include/nvgpu/lock.h @@ -1,5 +1,5 @@ /* - * Copyright (c) 2018-2020, NVIDIA CORPORATION. All rights reserved. + * Copyright (c) 2018-2021, NVIDIA CORPORATION. All rights reserved. * * Permission is hereby granted, free of charge, to any person obtaining a * copy of this software and associated documentation files (the "Software"), @@ -59,41 +59,41 @@ 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. + * + * @param mutex [in] Mutex to initialize. */ 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. + * + * @param mutex [in] Mutex to acquire. */ 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. + * + * @param mutex [in] Mutex to release. */ 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. * + * @param mutex [in] Mutex to try acquire. + * * @return Integer value to indicate whether the mutex was successfully acquired * or not. * @@ -105,77 +105,77 @@ 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. + * + * @param mutex [in] Mutex to destroy. */ 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. + * + * @param spinlock [in] Spinlock to initialize. */ 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. + * + * @param spinlock [in] Spinlock to acquire. */ 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. + * + * @param spinlock [in] Spinlock to release. */ 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. + * + * @param spinlock [in] Raw spinlock structure to initialize. */ 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. + * + * @param spinlock [in] Raw spinlock to acquire. */ 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. + * + * @param spinlock [in] Raw spinlock to release. */ void nvgpu_raw_spinlock_release(struct nvgpu_raw_spinlock *spinlock); diff --git a/drivers/gpu/nvgpu/include/nvgpu/posix/bitops.h b/drivers/gpu/nvgpu/include/nvgpu/posix/bitops.h index c2fce1c39..5c36302b5 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/posix/bitops.h +++ b/drivers/gpu/nvgpu/include/nvgpu/posix/bitops.h @@ -42,9 +42,9 @@ /** * @brief Convert number of bits into long. * - * @param bits [in] Number of bits to convert. - * * Converts the input param \a bits into equivalent number of long. + * + * @param bits [in] Number of bits to convert. */ #define BITS_TO_LONGS(bits) \ (nvgpu_safe_add_u64(bits, BITS_PER_LONG - 1UL) / BITS_PER_LONG) @@ -52,20 +52,20 @@ /** * @brief Set the bit value. * - * @param i [in] Bit position to set. - * * Invokes #BIT64 to set the value at bit position indicated by \a i. * Deprecated; use the explicit BITxx() macros instead. + * + * @param i [in] Bit position to set. */ #define BIT(i) BIT64(i) /** * @brief Create a bit mask. * + * Creates a bit mask starting at bit position \a lo and ending at \a hi. + * * @param hi [in] MSB position of the bit mask. * @param lo [in] LSB position of the bit mask. - * - * Creates a bit mask starting at bit position lo and ending at hi. */ #define GENMASK(hi, lo) \ (((~0UL) - (1UL << (lo)) + 1UL) & \ @@ -79,13 +79,13 @@ /** * @brief Create an array of unsigned long to represent a bitmap. * - * @param bmap [in] Bitmap to create. - * @param bits [in] Number of bits. - * * Creates an array of data type unsigned long by name \a bmap. The size of the * array is taken as \a bits value converted into an equivalent rounded up long - * value if the rounded up value is less than or equal to #LONG_MAX. Otherwise + * value if the rounded up value is less than or equal to LONG_MAX. Otherwise * the array declaration will generate a compiler error. + * + * @param bmap [in] Bitmap to create. + * @param bits [in] Number of bits. */ #define DECLARE_BITMAP(bmap, bits) \ unsigned long bmap[(((LONG_MAX - (bits)) < (BITS_PER_LONG - 1UL)) ? \ @@ -108,11 +108,11 @@ /** * @brief Find first set bit. * - * @param word [in] Input of datatype long. - * * Function returns the position of the first set bit in \a word. This function * internally uses the builtin function __builtin_ffsl. * + * @param word [in] Input of datatype long. + * * @return Returns one plus the index of the least significant 1-bit of input * param \a word. Returns 0 if input param is 0. */ @@ -121,11 +121,11 @@ unsigned long nvgpu_posix_ffs(unsigned long word); /** * @brief Find last set bit. * - * @param word [in] Input of datatype long. - * * Function returns the position of the last set bit in \a word. This function * internally uses the builtin function __builtin_clzl. * + * @param word [in] Input of datatype long. + * * @return Returns one plus the index of the most significant 1-bit of input * param word. If input param is 0, returns 0. */ @@ -144,10 +144,10 @@ unsigned long nvgpu_posix_fls(unsigned long word); /** * @brief Find first zero bit. * - * @param word [in] Input value to search for the bit. - * * Macro to find the position of first zero bit in input data \a word. * + * @param word [in] Input value to search for the bit. + * * @return Returns the bit position of first zero bit in the input data. */ #define ffz(word) (nvgpu_ffs(~(word)) - 1UL) @@ -155,11 +155,11 @@ unsigned long nvgpu_posix_fls(unsigned long word); /** * @brief Find the first set bit. * + * Finds the first set bit position in the input bitmap pointed by \a address. + * * @param address [in] Input value to search for set bit. * @param size [in] Size of the input value in bits. * - * Finds the first set bit position in the input data \a address. - * * @return Returns the position of first set bit. */ unsigned long find_first_bit(const unsigned long *address, unsigned long size); @@ -167,12 +167,12 @@ unsigned long find_first_bit(const unsigned long *address, unsigned long size); /** * @brief Finds the next set bit. * + * Finds the next set bit position in the input data \a address. + * * @param address [in] Input value to search for next set bit. * @param size [in] Size of the input value in bits. * @param offset [in] Offset to start from the input data. * - * Finds the next set bit position in the input data \a address. - * * @return Returns the position of next set bit. */ unsigned long find_next_bit(const unsigned long *address, unsigned long size, @@ -181,11 +181,11 @@ unsigned long find_next_bit(const unsigned long *address, unsigned long size, /** * @brief Finds the first zero bit. * + * Finds the first zero bit position in the input data \a address. + * * @param address [in] Input value to search. * @param size [in] Size of the input value in bits. * - * Finds the first zero bit position in the input data \a address. - * * @return Returns the position of first zero bit. */ unsigned long find_first_zero_bit(const unsigned long *address, @@ -194,12 +194,12 @@ unsigned long find_first_zero_bit(const unsigned long *address, /** * @brief Test the bit value at given position. * + * Checks if the bit at position mentioned by \a bit in \a address is set or + * not. + * * @param bit [in] Bit position to check. * @param address [in] Input data stream. * - * Checks if the bit at position mentioned by \a bit in \a address is set - * or not. - * * @return Boolean value which indicates the status of the bit. * * @retval TRUE if the bit position is set. @@ -210,11 +210,11 @@ bool nvgpu_test_bit(unsigned int bit, const volatile unsigned long *address); /** * @brief Test and set the bit at given position. * + * Tests and sets the bit at position \a bit in \a address. + * * @param bit [in] Bit position to test and set. * @param address [in] Input data stream. * - * Tests and sets the bit at position \a bit in \a address. - * * @return Boolean value which indicates the status of the bit before the set * operation. * @@ -226,11 +226,11 @@ bool nvgpu_test_and_set_bit(unsigned int bit, volatile unsigned long *address); /** * @brief Test and clear the bit at given position. * + * Tests and clears the bit at position \a bit in \a address. + * * @param bit [in] Bit position to test and clear. * @param address [in] Input data stream. * - * Tests and clears the bit at position \a bit in \a address. - * * @return Boolean value which indicates the status of the bit before the clear * operation. * @@ -247,44 +247,44 @@ bool nvgpu_test_and_clear_bit(unsigned int bit, /** * @brief Sets the bit at given position. * + * Sets the bit atomically at bit position \a bit in \a address. + * * @param bit [in] Bit position to set. * @param address [in] Input data stream. - * - * Sets the bit atomically at bit position \a bit in \a address. */ void nvgpu_set_bit(unsigned int bit, volatile unsigned long *address); /** * @brief Clears the bit at given position. * + * Clears the bit atomically at bit position \a bit in \a address. + * * @param bit [in] Bit position to clear. * @param address [in] Input data stream. - * - * Clears the bit atomically at bit position \a bit in \a address. */ void nvgpu_clear_bit(unsigned int bit, volatile unsigned long *address); /** * @brief Sets a bitmap. * + * Sets a bitmap of length \a len starting from bit position \a start in + * \a map. + * * @param map [in,out] Input data to set bitmap. * @param start [in] Start position of the bitmap. * @param len [in] Length of the bitmap. - * - * Sets a bitmap of length \a len starting from bit position \a start in - * \a map. */ void nvgpu_bitmap_set(unsigned long *map, unsigned int start, unsigned int len); /** * @brief Clears a bitmap. * + * Clears a bitmap of length \a len starting from bit position \a start in + * \a map. + * * @param map [in,out] Input data to clear bitmap. * @param start [in] Start position of the bitmap. * @param len [in] Length of the bitmap. - * - * Clears a bitmap of length \a len starting from bit position \a start in - * \a map. */ void nvgpu_bitmap_clear(unsigned long *map, unsigned int start, unsigned int len); @@ -292,15 +292,15 @@ void nvgpu_bitmap_clear(unsigned long *map, unsigned int start, /** * @brief Find first bitmap space. * + * Searches a bitmap for the first space of contiguous zeros that is large + * enough to accommodate the requested number of bits. + * * @param map [in] Input data stream. * @param size [in] Size of the input data. * @param start [in] Start position in input. * @param bit [in] Number of bits in bitmap. * @param align_mask [in] Align mask for start. * - * Searches a bitmap for the first space of contiguous zeros that is large - * enough to accommodate the requested number of bits. - * * @return Returns the position at which the bitmap starts if enough free space * is present in the input stream to accommodate the bitmap; otherwise, return * the size of the input data. diff --git a/drivers/gpu/nvgpu/include/nvgpu/posix/bug.h b/drivers/gpu/nvgpu/include/nvgpu/posix/bug.h index e977eca53..448560884 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/posix/bug.h +++ b/drivers/gpu/nvgpu/include/nvgpu/posix/bug.h @@ -59,23 +59,26 @@ void dump_stack(void); /** * @brief Bug. * + * Function to be invoked upon identifying a bug in the code. This function + * checks for any callbacks registered by other units, and invoke them for a + * bug condition. If the callback list is empty, a SIGSEGV is raised to + * terminate the process. + * * @param msg [in] Message to be printed in log. * @param line_no [in] Line number. - * - * Function to be invoked upon identifying bug in the code. */ void nvgpu_posix_bug(const char *msg, int line_no) __attribute__ ((noreturn)); /** * @brief Issues Warning. * + * Used to report significant issues that needs prompt attention. + * Warning print is invoked if the condition is met. + * * @param cond [in] Condition to check to issue warning. * @param fmt [in] Format of variable argument list. * @param ... [in] Variable length arguments. * - * Used to report significant issues that needs prompt attention. - * Warning is issued if the condition is met. - * * @return Value of \a cond is returned. */ bool nvgpu_posix_warn(bool cond, const char *fmt, ...); @@ -131,36 +134,35 @@ struct nvgpu_bug_cb; /** * @brief Exit current process * - * @param status [in] Status to return - * * This function is used during BUG() handling to exit * current process. + * + * @param status [in] Status to return */ void nvgpu_bug_exit(int status); /** * @brief Register callback to be invoked on BUG() * - * @param cb [in] Pointer to callback structure - * * Register a callback to be invoked on BUG(). * The nvgpu_bug_cb structure contains a function pointer * and an argument to be passed to this function. * This mechanism can be used to perform some emergency * operations on a GPU before exiting the process. - * * Note: callback is automatically unregistered before * being invoked. + * + * @param cb [in] Pointer to callback structure */ void nvgpu_bug_register_cb(struct nvgpu_bug_cb *cb); /** * @brief Unregister a callback for BUG() * - * @param cb [in] Pointer to callback structure - * * Remove a callback from the list of callbacks to be * invoked on BUG(). + * + * @param cb [in] Pointer to callback structure */ void nvgpu_bug_unregister_cb(struct nvgpu_bug_cb *cb); diff --git a/drivers/gpu/nvgpu/include/nvgpu/posix/circ_buf.h b/drivers/gpu/nvgpu/include/nvgpu/posix/circ_buf.h index b323c6321..5d9b82ee7 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/posix/circ_buf.h +++ b/drivers/gpu/nvgpu/include/nvgpu/posix/circ_buf.h @@ -1,5 +1,5 @@ /* - * Copyright (c) 2018-2020, NVIDIA CORPORATION. All rights reserved. + * Copyright (c) 2018-2021, NVIDIA CORPORATION. All rights reserved. * * Permission is hereby granted, free of charge, to any person obtaining a * copy of this software and associated documentation files (the "Software"), @@ -28,13 +28,13 @@ /** * @brief Return count in buffer. * + * Calculates the number of elements present in the circular buffer and + * returns the value. The circular buffer should have a power of 2 size. + * * @param head [in] Head of the buffer. * @param tail [in] Tail of the buffer. * @param size [in] Max number of elements in buffer. * - * Calculates the number of elements present in the circular buffer and - * returns the value. - * * @return Count of elements in the buffer. */ #define CIRC_CNT(head, tail, size) (((head) - (tail)) & ((size)-1U)) @@ -42,12 +42,13 @@ /** * @brief Return space in buffer. * + * Calculates the space available in the circular buffer and returns the value. + * The circular buffer should have a power of 2 size. + * * @param head [in] Head of the buffer. * @param tail [in] Tail of the buffer. * @param size [in] Max number of elements in buffer. * - * Calculates the space available in the circular buffer and returns the value. - * * @return The space available in the buffer. */ #define CIRC_SPACE(head, tail, size) CIRC_CNT((tail), ((head)+1U), (size)) diff --git a/drivers/gpu/nvgpu/include/nvgpu/posix/cond.h b/drivers/gpu/nvgpu/include/nvgpu/posix/cond.h index af5189b76..999c46ad3 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/posix/cond.h +++ b/drivers/gpu/nvgpu/include/nvgpu/posix/cond.h @@ -68,11 +68,11 @@ struct nvgpu_posix_fault_inj *nvgpu_cond_broadcast_get_fault_injection(void); /** * @brief Timed wait for a condition variable. * + * Waits for a condition variable for the time duration passed as param \a ms. + * * @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. The error number returned are either * generated by this function or generated by one of the OS APIs used @@ -96,28 +96,28 @@ int nvgpu_cond_timedwait(struct nvgpu_cond *c, unsigned int *ms); /** * @brief Signal a condition variable. * + * 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. + * * @param cond [in] Condition variable to signal. * - Should not be equal to NULL. * - Structure pointed by \a cond should be initialized * before invoking this function. - * - * 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. - * - Structure pointed by \a cond should be initialized - * before invoking this function. - * * 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. * + * @param cond [in] Condition variable to broadcast. + * - Structure pointed by \a cond should be initialized + * before invoking this function. + * * @return If successful a value of 0 shall be returned; otherwise, an error * number to indicate the error is returned. * @@ -132,36 +132,36 @@ int nvgpu_cond_broadcast_locked(struct nvgpu_cond *cond); /** * @brief Acquire the mutex associated with condition variable. * + * Acquires the mutex associated with the condition variable referenced + * by the param \a cond. + * * @param cond [in] Condition variable for which the mutex has to be * acquired. Structure pointed by \a cond has to be * initialized before invoking this function. - * - * 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. + * + * @param cond [in] Condition variable for which the mutex has to be + * released. */ void nvgpu_cond_unlock(struct nvgpu_cond *cond); /** * @brief Wait for a condition to be true. * + * Wait for a condition to become true. Differentiates between timed wait + * and infinite wait from the parameter \a timeout_ms. + * * @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. Differentiates between timed wait - * and infinite wait from the parameter \a timeout_ms. - * * @return If successful, this macro returns 0. Otherwise, an error number * is returned to indicate the error. * @@ -191,13 +191,13 @@ void nvgpu_cond_unlock(struct nvgpu_cond *cond); /** * @brief Initiate a wait for a condition variable. * + * Wait for a condition to become true. Acquires the mutex associated with the + * condition variable before attempting to 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. Acquires the mutex associated with the - * condition variable before attempting to wait. - * * @return If successful, this macro returns 0. Otherwise, an error number * is returned to indicate the error. * @@ -230,14 +230,14 @@ void nvgpu_cond_unlock(struct nvgpu_cond *cond); /** * @brief Interruptible 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 timeout_ms [in] Timeout in milliseconds or 0 for infinite wait. - * * 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. * + * @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. + * * @return If successful, this macro returns 0. Otherwise, an error number * is returned to indicate the error. * @@ -259,14 +259,14 @@ void nvgpu_cond_unlock(struct nvgpu_cond *cond); /** * @brief Wait for a condition to be true. * + * Wait for a condition to become true. Invokes the function + * nvgpu_cond_timedwait internally. + * * @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. Invokes the function - * nvgpu_cond_timedwait internally. - * * @return If successful, this macro returns 0. Otherwise, an error number * is returned to indicate the error. * diff --git a/drivers/gpu/nvgpu/include/nvgpu/posix/file_ops.h b/drivers/gpu/nvgpu/include/nvgpu/posix/file_ops.h index f49237316..4b88edb35 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/posix/file_ops.h +++ b/drivers/gpu/nvgpu/include/nvgpu/posix/file_ops.h @@ -1,5 +1,5 @@ /* - * Copyright (c) 2019-2020, NVIDIA CORPORATION. All rights reserved. + * Copyright (c) 2019-2021, NVIDIA CORPORATION. All rights reserved. * * Permission is hereby granted, free of charge, to any person obtaining a * copy of this software and associated documentation files (the "Software"), @@ -40,13 +40,13 @@ struct nvgpu_posix_fault_inj *nvgpu_file_ops_get_fread_injection(void); /** * @brief Get file status. * - * @param fd [in] File descriptor. - * @param buf [out] Pointer to a buffer to store the status information. - * * The function shall obtain information about an open file associated with the * file descriptor \a fd. The \a buf argument is a pointer to a stat structure, * into which the information regarding the file is placed. * + * @param fd [in] File descriptor. + * @param buf [out] Pointer to a buffer to store the status information. + * * @return Upon successful completion, 0 shall be returned. Otherwise, -1 shall * be returned. */ @@ -55,13 +55,13 @@ int nvgpu_fstat(int fd, struct stat *buf); /** * @brief Read bytes from file. * + * The function attempts to read \a nbytes bytes from the file associated with + * the open file descriptor, \a fildes, into the buffer pointed by \a buf. + * * @param fildes [in] Descriptor of the file to read from. * @param buf [out] Pointer to a buffer to store the read data. * @param nbytes [in] Number of bytes to read. * - * The function attempts to read \a nbytes bytes from the file associated with - * the open file descriptor, \a fildes, into the buffer pointed by \a buf. - * * @return Number of bytes actually read, or -1. */ ssize_t nvgpu_fread(int fildes, void* buf, size_t nbytes); @@ -69,9 +69,9 @@ ssize_t nvgpu_fread(int fildes, void* buf, size_t nbytes); /** * @brief Close a file. * - * @param fd [in] Descriptor of the file to close. - * * The function closes the file specified by the file descriptor \a fd. + * + * @param fd [in] Descriptor of the file to close. */ void nvgpu_close(int fd); #endif /* NVGPU_POSIX_FILE_OPS_H */ diff --git a/drivers/gpu/nvgpu/include/nvgpu/posix/lock.h b/drivers/gpu/nvgpu/include/nvgpu/posix/lock.h index 3192bc7e3..349f1a197 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/posix/lock.h +++ b/drivers/gpu/nvgpu/include/nvgpu/posix/lock.h @@ -44,10 +44,10 @@ struct nvgpu_posix_lock { /** * @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. + * + * @param lock [in] Lock to acquire. */ static inline void nvgpu_posix_lock_acquire(struct nvgpu_posix_lock *lock) { @@ -58,11 +58,11 @@ static inline void nvgpu_posix_lock_acquire(struct nvgpu_posix_lock *lock) /** * @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. * + * @param lock [in] Lock to acquire. + * * @return Returns 0 on success; otherwise, returns error number. The return * values are generated by the OS API internally invoked by this function. * @@ -86,10 +86,10 @@ static inline int nvgpu_posix_lock_try_acquire( /** * @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. + * + * @param lock [in] Lock to release. */ static inline void nvgpu_posix_lock_release(struct nvgpu_posix_lock *lock) { diff --git a/drivers/gpu/nvgpu/include/nvgpu/posix/log2.h b/drivers/gpu/nvgpu/include/nvgpu/posix/log2.h index 87c4665cf..f9d75163c 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/posix/log2.h +++ b/drivers/gpu/nvgpu/include/nvgpu/posix/log2.h @@ -28,11 +28,11 @@ /** * @brief Integer logarithm for base 2. * - * @param x [in] The number to get the log for. - * * Calculates the log to the base 2 of input value \a x and returns the * integer value of the same. * + * @param x [in] The number to get the log for. + * * @return Integer value of log to the base 2 of input \a x. */ #define ilog2(x) ({ \ @@ -46,11 +46,11 @@ /** * @brief Round up to the power of two. * + * Rounds up the input number \a x to power of two and returns. + * * @param x [in] Number to round up. * - 0 is not a valid value. * - * Rounds up the input number \a x to power of two and returns. - * * @return Input value \a x rounded up to the power of two. */ #define roundup_pow_of_two(x) \ @@ -69,11 +69,11 @@ /** * @brief Round down to the power of two. * + * Rounds down the input number \a x to power of two and returns. + * * @param x [in] Number to round down. * - 0 is not a valid value. * - * Rounds down the input number \a x to power of two and returns. - * * @return Input value \a x rounded down to the power of two. */ #define rounddown_pow_of_two(x) \ @@ -92,10 +92,10 @@ /** * @brief Check for power of 2. * - * @param x [in] Number to check. - * * Checks if the input value \a x is a power of two or not. * + * @param x [in] Number to check. + * * @return True if the input \a x is a power of two, else returns false. */ #define is_power_of_2(x) \ diff --git a/drivers/gpu/nvgpu/include/nvgpu/posix/queue.h b/drivers/gpu/nvgpu/include/nvgpu/posix/queue.h index c8b537918..2df9a0c36 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/posix/queue.h +++ b/drivers/gpu/nvgpu/include/nvgpu/posix/queue.h @@ -61,11 +61,11 @@ struct nvgpu_queue { /** * @brief Calculate the unused message queue length. * - * @param queue [in] Queue structure to use. - * * The size of all the messages currently enqueued is subtracted from the total * size of the queue to get the unused queue length. * + * @param queue [in] Queue structure to use. + * * @return Return unused queue length. */ unsigned int nvgpu_queue_unused(struct nvgpu_queue *queue); @@ -73,10 +73,10 @@ unsigned int nvgpu_queue_unused(struct nvgpu_queue *queue); /** * @brief Calculate the length of the message queue in use. * - * @param queue [in] Queue structure to use. - * * Returns the size of all the messages currently enqueued in the queue. * + * @param queue [in] Queue structure to use. + * * @return Return the size of all the messages currently enqueued in the queue. */ unsigned int nvgpu_queue_available(struct nvgpu_queue *queue); @@ -84,6 +84,9 @@ unsigned int nvgpu_queue_available(struct nvgpu_queue *queue); /** * @brief Allocate memory and initialize the message queue variables. * + * Allocates memory for the message queue. Also initializes the message queue + * variables "in", "out" and "mask". + * * @param queue [in] Queue structure to use. * - Structure should not be equal to NULL * @param size [in] Size of the queue. @@ -92,9 +95,6 @@ unsigned int nvgpu_queue_available(struct nvgpu_queue *queue); * power of two is rounded up to the nearest power of * two. Hence this max size limit. * - * Allocates memory for the message queue. Also initializes the message queue - * variables "in", "out" and "mask". - * * @return Return 0 on success, otherwise returns error number to indicate the * error. * @@ -106,24 +106,24 @@ int nvgpu_queue_alloc(struct nvgpu_queue *queue, unsigned int size); /** * @brief Free the allocated memory for the message queue. * - * @param queue [in] Queue structure to use. - * * Free the allocated memory for the message queue. Also resets the message * queue variables "in", "out" and "mask". + * + * @param queue [in] Queue structure to use. */ void nvgpu_queue_free(struct nvgpu_queue *queue); /** * @brief Enqueue message into message queue. * - * @param queue [in] Queue structure to use. - * @param buf [in] Pointer to source message buffer. - * @param len [in] Size of the message to be enqueued. - * * Enqueues the message pointed by \a buf into the message queue and advances * the "in" index of the message queue by \a len which is the size of the * enqueued message. * + * @param queue [in] Queue structure to use. + * @param buf [in] Pointer to source message buffer. + * @param len [in] Size of the message to be enqueued. + * * @return Returns \a len on success, otherwise returns error number to indicate * the error. * @@ -136,17 +136,17 @@ int nvgpu_queue_in(struct nvgpu_queue *queue, const void *buf, /** * @brief Enqueue message into message queue after acquiring the mutex lock. * - * @param queue [in] Queue structure to use. - * @param buf [in] Pointer to source message buffer. - * @param len [in] Size of the message to be enqueued. - * @param lock [in] Mutex lock for concurrency management. - * * Acquires the mutex lock pointed by \a lock before enqueue operation. * Enqueues the message pointed by \a buf into the message queue and advances * the "in" index of the message queue by \a len which is the size of the * enqueued message once the lock is acquired. The lock is released after the * enqueue operation is completed. * + * @param queue [in] Queue structure to use. + * @param buf [in] Pointer to source message buffer. + * @param len [in] Size of the message to be enqueued. + * @param lock [in] Mutex lock for concurrency management. + * * @return Returns \a len on success, otherwise returns error number to indicate * the error. * @@ -159,13 +159,13 @@ int nvgpu_queue_in_locked(struct nvgpu_queue *queue, const void *buf, /** * @brief Dequeue message from message queue. * + * Dequeues the message of size \a len from the message queue and copies the + * same to \a buf. Also advances the "out" index of the queue by \a len. + * * @param queue [in] Queue structure to use. * @param buf [in] Pointer to destination message buffer. * @param len [in] Size of the message to be dequeued. * - * Dequeues the message of size \a len from the message queue and copies the - * same to \a buf. Also advances the "out" index of the queue by \a len. - * * @return Returns \a len on success, otherwise returns error number to indicate * the error. * @@ -178,16 +178,16 @@ int nvgpu_queue_out(struct nvgpu_queue *queue, void *buf, /** * @brief Dequeue message from message queue after acquiring the mutex lock. * - * @param queue [in] Queue structure to use. - * @param buf [in] Pointer to destination message buffer. - * @param len [in] Size of the message to be dequeued. - * @param lock [in] Mutex lock for concurrency management. - * * Acquires the mutex lock pointed by \a lock before dequeue operation. * Dequeues the message of size \a len from the message queue and copies the * same to \a buf. Also advances the "out" index of the queue by \a len. * Releases the mutex after the dequeue operation is completed. * + * @param queue [in] Queue structure to use. + * @param buf [in] Pointer to destination message buffer. + * @param len [in] Size of the message to be dequeued. + * @param lock [in] Mutex lock for concurrency management. + * * @return Returns \a len on success, otherwise returns error number to indicate * the error. * diff --git a/drivers/gpu/nvgpu/include/nvgpu/posix/thread.h b/drivers/gpu/nvgpu/include/nvgpu/posix/thread.h index d1114e0e1..ea3473684 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/posix/thread.h +++ b/drivers/gpu/nvgpu/include/nvgpu/posix/thread.h @@ -131,14 +131,14 @@ struct nvgpu_posix_fault_inj *nvgpu_thread_serial_get_fault_injection(void); /** * @brief Create a thread with specified priority. * + * Create a thread with requested priority and run threadfn in it. + * * @param thread [in] Thread to create. * @param data [in] Data to pass to threadfn. * @param threadfn [in] Thread function. * @param priority [in] Priority of the thread to be created. * @param name [in] Name of the thread. * - * Create a thread with requested priority and run threadfn in it. - * * @return Return 0 on success, else return the error number to indicate the * error. The error numbers returned are generated by the OS APIs invoked * internally by this function. diff --git a/drivers/gpu/nvgpu/include/nvgpu/posix/timers.h b/drivers/gpu/nvgpu/include/nvgpu/posix/timers.h index 458348424..9454e940c 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/posix/timers.h +++ b/drivers/gpu/nvgpu/include/nvgpu/posix/timers.h @@ -1,5 +1,5 @@ /* - * Copyright (c) 2019-2020, NVIDIA CORPORATION. All rights reserved. + * Copyright (c) 2019-2021, NVIDIA CORPORATION. All rights reserved. * * Permission is hereby granted, free of charge, to any person obtaining a * copy of this software and associated documentation files (the "Software"), @@ -33,14 +33,14 @@ /** * @brief Private handler of CPU timeout, should not be used directly. * + * Posix implementation of the CPU timeout handler. Checks if the timeout + * duration has expired or not. + * * @param timeout [in] Timeout object. * @param caller [in] Instruction pointer of the caller. * @param fmt [in] Format of the variable length argument. * @param arg... [in] Variable length arguments. * - * Posix implementation of the CPU timeout handler. Checks if the timeout - * duration has expired or not. - * * @return Shall return 0 if the timeout has not expired; otherwise, an error * number indicating a timeout is returned. * @@ -63,15 +63,15 @@ /** * @brief Private handler of retry timeout, should not be used directly. * + * Posix implementation of the retry timeout handler. Checks if the retry limit + * has reached, return an error value to indicate a timeout if the retry limit + * has reached else increment the retry count and return. + * * @param timeout [in] Timeout object. * @param caller [in] Instruction pointer of the caller. * @param fmt [in] Format of the variable length argument. * @param arg... [in] Variable length arguments. * - * Posix implementation of the retry timeout handler. Checks if the retry limit - * has reached, return an error value to indicate a timeout if the retry limit - * has reached else increment the retry count and return. - * * @return Shall return 0 if the timeout has not expired; otherwise, an error * number indicating a timeout is returned. * @@ -96,14 +96,14 @@ /** * @brief Private handler of userspace timeout, should not be used directly. * + * Posix implementation of the timeout handler. Differentiates between a CPU + * timer and a retry timer and handles accordingly. + * * @param timeout [in] Timeout object. * @param caller [in] Instruction pointer of the caller. * @param fmt [in] Format of the variable length argument. * @param arg... [in] Variable length arguments. * - * Posix implementation of the timeout handler. Differentiates between a CPU - * timer and a retry timer and handles accordingly. - * * @return Shall return 0 if the timeout has not expired; otherwise, an error * number indicating a timeout is returned. * diff --git a/drivers/gpu/nvgpu/include/nvgpu/posix/utils.h b/drivers/gpu/nvgpu/include/nvgpu/posix/utils.h index 9416077f7..c6a2dab52 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/posix/utils.h +++ b/drivers/gpu/nvgpu/include/nvgpu/posix/utils.h @@ -360,10 +360,10 @@ /** * @brief Endian conversion. * - * @param x [in] Value to be converted. - * * Converts the input value x in big endian to CPU byte order. * + * @param x [in] Value to be converted. + * * @return Endianness converted value of \a x. */ static inline u32 be32_to_cpu(u32 x) @@ -382,10 +382,10 @@ static inline u32 be32_to_cpu(u32 x) /** * @brief Hamming weight of 8 bit input value. * - * @param x [in] Input to find the hamming weight of. - * * Returns the hamming weight(number of non zero bits) of the input param \a x. * + * @param x [in] Input to find the hamming weight of. + * * @return Hamming weight of \a x. */ static inline unsigned int nvgpu_posix_hweight8(uint8_t x) @@ -412,10 +412,10 @@ static inline unsigned int nvgpu_posix_hweight8(uint8_t x) /** * @brief Hamming weight of 16 bit input value. * - * @param x [in] Input to find the hamming weight of. - * * Returns the hamming weight(number of non zero bits) of the input param \a x. * + * @param x [in] Input to find the hamming weight of. + * * @return Hamming weight of \a x. */ static inline unsigned int nvgpu_posix_hweight16(uint16_t x) @@ -433,10 +433,10 @@ static inline unsigned int nvgpu_posix_hweight16(uint16_t x) /** * @brief Hamming weight of 32 bit input value. * - * @param x [in] Input to find the hamming weight of. - * * Returns the hamming weight(number of non zero bits) of the input param \a x. * + * @param x [in] Input to find the hamming weight of. + * * @return Hamming weight of \a x. */ static inline unsigned int nvgpu_posix_hweight32(uint32_t x) @@ -454,10 +454,10 @@ static inline unsigned int nvgpu_posix_hweight32(uint32_t x) /** * @brief Hamming weight of 64 bit input value. * - * @param x [in] Input to find the hamming weight of. - * * Returns the hamming weight(number of non zero bits) of the input param \a x. * + * @param x [in] Input to find the hamming weight of. + * * @return Hamming weight of \a x. */ static inline unsigned int nvgpu_posix_hweight64(uint64_t x) diff --git a/drivers/gpu/nvgpu/include/nvgpu/rwsem.h b/drivers/gpu/nvgpu/include/nvgpu/rwsem.h index 171045f92..5449213b4 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/rwsem.h +++ b/drivers/gpu/nvgpu/include/nvgpu/rwsem.h @@ -1,5 +1,5 @@ /* - * Copyright (c) 2017-2019, NVIDIA CORPORATION. All rights reserved. + * Copyright (c) 2017-2021, NVIDIA CORPORATION. All rights reserved. * * Permission is hereby granted, free of charge, to any person obtaining a * copy of this software and associated documentation files (the "Software"), @@ -40,49 +40,49 @@ struct nvgpu_rwsem; /** * @brief Initialize read write lock. * - * @param rwsem [in] Read,write lock to initialize. - * * Initializes the read,write lock referenced by \a rwsem. + * + * @param rwsem [in] Read,write lock to initialize. */ void nvgpu_rwsem_init(struct nvgpu_rwsem *rwsem); /** * @brief Acquire read lock. * - * @param rwsem [in] Read,write lock to be locked for read. - * * Acquires a read lock on the read,write lock object referenced by \a rwsem. * The calling thread acquires a read lock if no writer is holding the lock * on \a rwsem. + * + * @param rwsem [in] Read,write lock to be locked for read. */ void nvgpu_rwsem_up_read(struct nvgpu_rwsem *rwsem); /** * @brief Release read lock. * - * @param rwsem [in] Read,write lock to be released. - * * Releases the lock held on \a rwsem. To be used to release a read lock. + * + * @param rwsem [in] Read,write lock to be released. */ void nvgpu_rwsem_down_read(struct nvgpu_rwsem *rwsem); /** * @brief Acquire write lock. * - * @param rwsem [in] Read,write lock to be locked for write. - * * Acquires the write lock on \a rwsem. The calling thread acquires write lock * if no other thread is holding a lock on rwsem. + * + * @param rwsem [in] Read,write lock to be locked for write. */ void nvgpu_rwsem_up_write(struct nvgpu_rwsem *rwsem); /** * @brief Release the write lock. * - * @param rwsem [in] Read,write lock to be released. - * * Releases the write lock held on \a rwsem. To be used to release a write * lock. + * + * @param rwsem [in] Read,write lock to be released. */ void nvgpu_rwsem_down_write(struct nvgpu_rwsem *rwsem); diff --git a/drivers/gpu/nvgpu/include/nvgpu/thread.h b/drivers/gpu/nvgpu/include/nvgpu/thread.h index 1df62b556..8c6d6528e 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/thread.h +++ b/drivers/gpu/nvgpu/include/nvgpu/thread.h @@ -1,5 +1,5 @@ /* - * Copyright (c) 2017-2020, NVIDIA CORPORATION. All rights reserved. + * Copyright (c) 2017-2021, NVIDIA CORPORATION. All rights reserved. * * Permission is hereby granted, free of charge, to any person obtaining a * copy of this software and associated documentation files (the "Software"), @@ -35,16 +35,16 @@ /** * @brief Create and run a new thread. * - * @param thread [in] Thread structure to use. - * @param data [in] Data to pass to threadfn. - * @param threadfn [in] Thread function. - * @param name [in] Name of the thread. - * * Create a thread and run threadfn in it. The thread stays alive as long as * threadfn is running. As soon as threadfn returns the thread is destroyed. * The threadfn needs to continuously poll #nvgpu_thread_should_stop() to * determine if it should exit. * + * @param thread [in] Thread structure to use. + * @param data [in] Data to pass to threadfn. + * @param threadfn [in] Thread function. + * @param name [in] Name of the thread. + * * @return Return 0 on success, otherwise returns error number to indicate the * error. * @@ -60,24 +60,24 @@ int nvgpu_thread_create(struct nvgpu_thread *thread, /** * @brief Stop a thread. * - * @param thread [in] Thread to stop. - * * A thread can be requested to stop by calling this function. This function * places a request to cancel the corresponding thread by setting a status and * waits until that thread exits. + * + * @param thread [in] Thread to stop. */ void nvgpu_thread_stop(struct nvgpu_thread *thread); /** * @brief Request a thread to be stopped gracefully. * - * @param thread [in] Thread to stop. - * @param thread_stop_fn [in] Callback function to trigger graceful exit. - * @param data [in] Thread data. - * * Request a thread to stop by setting the status of the thread appropriately. * In posix implementation, the callback function \a thread_stop_fn is invoked * and waits till the thread exits. + * + * @param thread [in] Thread to stop. + * @param thread_stop_fn [in] Callback function to trigger graceful exit. + * @param data [in] Thread data. */ void nvgpu_thread_stop_graceful(struct nvgpu_thread *thread, void (*thread_stop_fn)(void *data), void *data); @@ -85,11 +85,11 @@ void nvgpu_thread_stop_graceful(struct nvgpu_thread *thread, /** * @brief Query if thread should stop. * - * @param thread [in] Thread to be queried for stop status. - * * Return true if thread should exit. Can be run only in the thread's own * context. * + * @param thread [in] Thread to be queried for stop status. + * * @return Boolean value which indicates if the thread has to stop or not. * * @retval TRUE if the thread should stop. @@ -100,10 +100,10 @@ bool nvgpu_thread_should_stop(struct nvgpu_thread *thread); /** * @brief Query if thread is running. * - * @param thread [in] Thread to be queried for running status. - * * Returns a boolean value based on the current running status of the thread. * + * @param thread [in] Thread to be queried for running status. + * * @return TRUE if the current running status of the thread is 1, else FALSE. * * @retval TRUE if the thread is running. @@ -114,9 +114,9 @@ bool nvgpu_thread_is_running(struct nvgpu_thread *thread); /** * @brief Join a thread to reclaim resources after it has exited. * - * @param thread [in] - Thread to join. - * * The calling thread waits till the thread referenced by \a thread exits. + * + * @param thread [in] - Thread to join. */ void nvgpu_thread_join(struct nvgpu_thread *thread); diff --git a/drivers/gpu/nvgpu/include/nvgpu/timers.h b/drivers/gpu/nvgpu/include/nvgpu/timers.h index 6dc361aa9..dcf2ff61c 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/timers.h +++ b/drivers/gpu/nvgpu/include/nvgpu/timers.h @@ -116,6 +116,8 @@ struct nvgpu_timeout { /** * @brief Initialize a timeout. * + * Initialize a timeout object referenced by \a timeout. + * * @param g [in] GPU driver structure. * @param timeout [in] Timeout object to initialize. * @param duration [in] Timeout duration/count. @@ -124,8 +126,6 @@ struct nvgpu_timeout { * - NVGPU_TIMER_NO_PRE_SI * - NVGPU_TIMER_SILENT_TIMEOUT * - * Initialize a timeout object referenced by \a timeout. - * * @return Shall return 0 on success; otherwise, return error number to indicate * the error type. * @@ -137,11 +137,11 @@ int nvgpu_timeout_init(struct gk20a *g, struct nvgpu_timeout *timeout, /** * @brief Check the timeout status. * - * @param timeout [in] Timeout object to check the status. - * * Checks the status of \a timeout and returns if the timeout has expired or * not. * + * @param timeout [in] Timeout object to check the status. + * * @return Boolean value to indicate the status of timeout. * * @retval TRUE if the timeout has expired. @@ -152,14 +152,14 @@ bool nvgpu_timeout_peek_expired(struct nvgpu_timeout *timeout); /** * @brief Checks the timeout expiry according to the timer type. * - * @param __timeout [in] Timeout object to handle. - * * This macro checks to see if a timeout has expired. For retry based timers, * a call of this macro increases the retry count by one and checks if the * retry count has reached maximum allowed retry limit. For CPU based timers, * a call of this macro checks whether the required duration has elapsed. * Refer to the documentation of the function #nvgpu_timeout_expired_msg_impl * for underlying implementation. + * + * @param __timeout [in] Timeout object to handle. */ #define nvgpu_timeout_expired(__timeout) \ nvgpu_timeout_expired_msg_impl(__timeout, NVGPU_GET_IP, "") @@ -167,13 +167,13 @@ bool nvgpu_timeout_peek_expired(struct nvgpu_timeout *timeout); /** * @brief Checks the timeout expiry and uses the input params for debug message. * - * @param __timeout [in] Timeout object to handle. - * @param fmt [in] Format of the variable arguments. - * @param args... [in] Variable arguments. - * * Along with handling the timeout, this macro also takes in a variable list * of arguments which is used in constructing the debug message for a timeout. * Refer to #nvgpu_timeout_expired for further details. + * + * @param __timeout [in] Timeout object to handle. + * @param fmt [in] Format of the variable arguments. + * @param args... [in] Variable arguments. */ #define nvgpu_timeout_expired_msg(__timeout, fmt, args...) \ nvgpu_timeout_expired_msg_impl(__timeout, NVGPU_GET_IP, fmt, ##args) @@ -185,34 +185,34 @@ bool nvgpu_timeout_peek_expired(struct nvgpu_timeout *timeout); /** * @brief Sleep for millisecond intervals. * - * @param msecs [in] Milliseconds to sleep. - * * Function sleeps for requested millisecond duration. + * + * @param msecs [in] Milliseconds to sleep. */ void nvgpu_msleep(unsigned int msecs); /** * @brief Sleep for a duration in the range of input parameters. * - * @param min_us [in] Minimum duration to sleep in microseconds. - * @param max_us [in] Maximum duration to sleep in microseconds. - * * Sleeps for a value in the range between min_us and max_us. The underlying * implementation is OS dependent. In nvgpu posix implementation, the sleep is * always for min_us duration and the function sleeps only if the input min_us * value is greater than or equal to 1000 microseconds, else the function just * delays execution for requested duration of time without sleeping. + * + * @param min_us [in] Minimum duration to sleep in microseconds. + * @param max_us [in] Maximum duration to sleep in microseconds. */ void nvgpu_usleep_range(unsigned int min_us, unsigned int max_us); /** * @brief Delay execution. * - * @param usecs [in] Delay duration in microseconds. - * * Delays the execution for requested duration of time in microseconds. In * posix implementation, if the requested duration is greater than or equal to * 1000 microseconds, the function sleeps. + * + * @param usecs [in] Delay duration in microseconds. */ void nvgpu_udelay(unsigned int usecs); @@ -271,12 +271,12 @@ u64 nvgpu_hr_timestamp(void); /** * @brief OS specific implementation to provide precise microsecond delay * + * Wait using nanospin_ns until usecs expires. Log error if API returns non + * zero value once wait time expires. + * * @param usecs [in] Delay in microseconds. * Range: 0 - 500ms. * - * - Wait using nanospin_ns until usecs expires. Log error if API returns non - * zero value once wait time expires. - * * @return None. */ void nvgpu_delay_usecs(unsigned int usecs);