gpu: nvgpu: update doxygen comments for utils

Update the doxygen comments for common utils unit.

Jira NVGPU-6236

Change-Id: I2d842baaf2efea66673f700b6926c6a16b468bbd
Signed-off-by: ajesh <akv@nvidia.com>
Reviewed-on: https://git-master.nvidia.com/r/c/linux-nvgpu/+/2457841
(cherry picked from commit 88b83544696c350933082c8c88bce985837213ac)
Reviewed-on: https://git-master.nvidia.com/r/c/linux-nvgpu/+/2459913
GVS: Gerrit_Virtual_Submit
Tested-by: mobile promotions <svcmobile_promotions@nvidia.com>
Reviewed-by: Rajesh Devaraj <rdevaraj@nvidia.com>
Reviewed-by: Vaibhav Kachore <vkachore@nvidia.com>
Reviewed-by: mobile promotions <svcmobile_promotions@nvidia.com>

drivers/gpu/nvgpu/include/nvgpu/enabled.h

@@ -221,7 +221,10 @@ enum enum_enabled_flags {
  * @param g [in]	The GPU.
  * @param flag [in]	Which flag to check.
  *
- * @retrun true if the passed \a flag is true; false otherwise.
+ * @return Boolean value to indicate the status of the bit.
+ *
+ * @retval TRUE if the flag bit is enabled.
+ * @retval FALSE if the flag bit is not enabled.
  */
 bool nvgpu_is_enabled(struct gk20a *g, u32 flag);
 
@@ -248,6 +251,7 @@ void nvgpu_set_enabled(struct gk20a *g, u32 flag, bool state);
  * @param g [in]	The GPU superstructure.
  *
  * @return 0 for success, < 0 for error.
+ *
  * @retval -ENOMEM if fails to allocate the necessary memory.
  */
 int nvgpu_init_enabled_flags(struct gk20a *g);

drivers/gpu/nvgpu/include/nvgpu/kref.h

@@ -42,7 +42,8 @@ struct nvgpu_ref {
  *
  * @param ref [in]	The nvgpu_ref object to initialize.
  *
- * Initializes the reference object pointed by \a ref.
+ * Initializes the reference count of the object pointed by \a ref by
+ * atomically setting it to 1.
  */
 static inline void nvgpu_ref_init(struct nvgpu_ref *ref)
 {
@@ -54,7 +55,7 @@ static inline void nvgpu_ref_init(struct nvgpu_ref *ref)
  *
  * @param ref [in]	The nvgpu_ref object.
  *
- * Increment reference count for the object
+ * Increment the reference count for the object atomically.
  */
 static inline void nvgpu_ref_get(struct nvgpu_ref *ref)
 {
@@ -100,6 +101,9 @@ static inline void nvgpu_ref_put(struct nvgpu_ref *ref,
  * not make any assumptions about the status of the object in the memory when
  * the function returns 0 and should only use it to know that there are no
  * further references to this object.
+ *
+ * @retval 1 if reference count becomes zero after decrement.
+ * @retval 0 if reference count is non-zero after decrement.
  */
 static inline int nvgpu_ref_put_return(struct nvgpu_ref *ref,
 		void (*release)(struct nvgpu_ref *r))
@@ -118,7 +122,8 @@ static inline int nvgpu_ref_put_return(struct nvgpu_ref *ref,
  *
  * @param ref [in]	The nvgpu_ref object.
  *
- * Increment the reference count of the object unless it is zero.
+ * Increment the reference count of the object pointed by \a ref unless it
+ * is zero.
  *
  * @return Return non-zero if the increment succeeds, Otherwise return 0.
  */

drivers/gpu/nvgpu/include/nvgpu/list.h

@@ -105,7 +105,10 @@ static inline void nvgpu_list_del(struct nvgpu_list_node *node)
  *
  * Checks if the list pointed by \a head is empty or not.
  *
- * @return return true if the list is empty, otherwise return false.
+ * @return Boolean value to indicate the status of the list.
+ *
+ * @retval TRUE if list is empty.
+ * @retval FALSE if list is not empty.
  */
 static inline bool nvgpu_list_empty(struct nvgpu_list_node *head)
 {
@@ -147,8 +150,6 @@ static inline void nvgpu_list_replace_init(struct nvgpu_list_node *old_node,
 	nvgpu_init_list_node(old_node);
 }
 
-/** @cond DOXYGEN_SHOULD_SKIP_THIS */
-
 /**
  * @brief Entry from the list
  *
@@ -176,8 +177,6 @@ static inline void nvgpu_list_replace_init(struct nvgpu_list_node *old_node,
 #define nvgpu_list_next_entry(pos, type, member)	\
 	nvgpu_list_entry((pos)->member.next, type, member)
 
-/** @endcond DOXYGEN_SHOULD_SKIP_THIS */
-
 /**
  * @brief First entry from the list.
  *

drivers/gpu/nvgpu/include/nvgpu/string.h

@@ -32,45 +32,67 @@
 struct gk20a;
 
 /**
- * nvgpu_memcpy - Copy memory buffer
+ * @brief Copy memory buffer
  *
- * @destb - Buffer into which data is to be copied.
- * @srcb - Buffer from which data is to be copied.
- * @n - Number of bytes to copy from src buffer to dest buffer.
+ * @param destb [out]	Buffer into which data is to be copied.
+ * @param srcb [in]	Buffer from which data is to be copied.
+ * @param n [in]	Number of bytes to copy from src buffer to dest buffer.
  *
  * Copy memory from source buffer to destination buffer.
  */
 void nvgpu_memcpy(u8 *destb, const u8 *srcb, size_t n);
 
 /**
- * nvgpu_memcmp - Compare memory buffers
+ * @brief Compare memory buffers
  *
- * @b1 - First buffer to use in memory comparison.
- * @b2 - Second buffer to use in memory comparison.
- * @n - Number of bytes to compare between buffer1 and buffer2.
+ * @param b1 [in]	First buffer to use in memory comparison.
+ * @param b2 [in]	Second buffer to use in memory comparison.
+ * @param n [in]	Number of bytes to compare between two buffers.
  *
- * Compare the first n bytes of two memory buffers.  If the contents of the
+ * Compare the first \a n bytes of two memory buffers.  If the contents of the
  * two buffers match then zero is returned.  If the contents of b1 are less
  * than b2 then a value less than zero is returned.  If the contents of b1
  * are greater than b2 then a value greater than zero is returned.
+ *
+ * @return 0 if the comparison matches else a non-zero value is returned.
+ *
+ * @retval 0 if both buffers match.
+ * @retval <0 if object pointed to by \a b1 is less than the object pointed to
+ * by \a b2.
+ * @retval >0 if object pointed to by \a b1 is greater than the object pointed
+ * to by \a b2.
  */
 int nvgpu_memcmp(const u8 *b1, const u8 *b2, size_t n);
 
 /**
- * nvgpu_strnadd_u32 - formats u32 into null-terminated string
+ * @brief Formats u32 into null-terminated string
  *
- * Returns number of digits added to string (not including '\0')
- * Returns 0 in case of invalid dst or radix, or insufficient space.
- * Returns 0 if there was no room to add '\0'
+ * @param dst [in,out]	Buffer to copy the value into.
+ * @param value [in]	Value to be added with the string.
+ * @param size [in]	Size available in the destination buffer.
+ * @param radix	[in]	Radix value to be used.
+ *
+ * Formats the integer variable \a value into a null terminated string.
+ *
+ * @return Returns number of digits added to string (not including '\0') if
+ * successful, else 0.
+ *
+ * @retval 0 in case of invalid radix or insufficient space.
  */
 int nvgpu_strnadd_u32(char *dst, const u32 value, size_t size, u32 radix);
 
 /**
- * nvgpu_mem_is_word_aligned - Check that memory address is word (4-byte)
- * aligned.
+ * @brief Check that memory address is word (4-byte) aligned.
  *
- * @g - struct gk20a.
- * @addr - memory address.
+ * @param g [in]	struct gk20a.
+ * @param addr [in]	Memory address.
+ *
+ * Checks if the provided address is word aligned or not.
+ *
+ * @return Boolean value to indicate the alignment status of the address.
+ *
+ * @retval TRUE if \a addr is word aligned.
+ * @retval FALSE if \a addr is not word aligned.
  */
 bool nvgpu_mem_is_word_aligned(struct gk20a *g, u8 *addr);
 

drivers/gpu/nvgpu/include/nvgpu/worker.h

@@ -200,11 +200,14 @@ struct nvgpu_worker {
  *
  * @param worker [in]	The worker
  *
- * @return true if the worker should stop. false otherwise.
- *
  * Generic function to be used for #nvgpu_worker_ops.wakeup_early_exit if there
  * are no special conditions required for the worker. This function returns
  * true if the thread should stop because it is no longer running.
+ *
+ * @return Boolean value indicating if the thread should stop or not.
+ *
+ * @retval TRUE if the worker thread should stop.
+ * @retval FALSE if the worker thread can continue running.
  */
 bool nvgpu_worker_should_stop(struct nvgpu_worker *worker);
 
@@ -219,7 +222,10 @@ bool nvgpu_worker_should_stop(struct nvgpu_worker *worker);
  * because in that case it has been scheduled already but has not yet been
  * processed.
  *
- * @return 0 if successfully added, < 0 value on error.
+ * @return Integer value indicating the status of enqueue operation.
+ *
+ * @retval 0 on success.
+ * @retval -1 on failure.
  */
 int nvgpu_worker_enqueue(struct nvgpu_worker *worker,
 		struct nvgpu_list_node *work_item);
@@ -242,7 +248,14 @@ void nvgpu_worker_init_name(struct nvgpu_worker *worker,
  * @param worker [in]	The worker.
  * @param ops [in]	The worker ops specific for this worker.
  *
- * @return 0 for success, < 0 for error.
+ * @return 0 for success, < 0 for error. This function internally invokes
+ * the thread creation API for worker thread. The error codes generated by the
+ * thread creation API will be returned by this function.
+ *
+ * @retval EINVAL invalid thread attribute object.
+ * @retval EAGAIN insufficient system resources to create thread.
+ * @retval EFAULT error occurred trying to access the buffers or the
+ * start routine provided for thread creation.
  */
 int nvgpu_worker_init(struct gk20a *g, struct nvgpu_worker *worker,
 		const struct nvgpu_worker_ops *ops);
@@ -254,4 +267,4 @@ int nvgpu_worker_init(struct gk20a *g, struct nvgpu_worker *worker,
  */
 void nvgpu_worker_deinit(struct nvgpu_worker *worker);
 
-#endif /* NVGPU_WORKER_H */
+#endif /* NVGPU_WORKER_H */