gpu: nvgpu: update doxygen for utils

Update the documentation as per SWUD feedback for utils
unit.

JIRA NVGPU-6962

Change-Id: Ia82d0d4692821aa96beec73a2f7f3e5aa1d44632
Signed-off-by: ajesh <akv@nvidia.com>
Reviewed-on: https://git-master.nvidia.com/r/c/linux-nvgpu/+/2571970
(cherry picked from commit 821a023424de64873493cd84cddfb14104c3d18e)
Reviewed-on: https://git-master.nvidia.com/r/c/linux-nvgpu/+/2586344
Reviewed-by: svcacv <svcacv@nvidia.com>
Reviewed-by: Vaibhav Kachore <vkachore@nvidia.com>
Reviewed-by: Ankur Kishore <ankkishore@nvidia.com>
Reviewed-by: mobile promotions <svcmobile_promotions@nvidia.com>
GVS: Gerrit_Virtual_Submit
Tested-by: mobile promotions <svcmobile_promotions@nvidia.com>

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

@@ -230,39 +230,65 @@ enum enum_enabled_flags {
 /**
  * @brief Check if the passed flag is enabled.
  *
- * @param g [in]	The GPU.
- * @param flag [in]	Which flag to check.
+ * Uses the function #nvgpu_test_bit() internally to check the status of the
+ * bit position indicated by the parameter \a flag. The input parameter \a flag
+ * and the variable \a enabled_flags in #gk20a are passed as parameters to the
+ * function #nvgpu_test_bit().
+ *
+ * @param g [in] GPU super structure. Function does not perform any
+ *		 validation of this parameter.
+ * @param flag [in] Which flag to check. Function validates if this
+ *		    parameter value is less than #NVGPU_MAX_ENABLED_BITS.
  *
  * @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.
+ * @retval FALSE if the flag bit is not enabled or if the flag value is greater
+ * than or equal to #NVGPU_MAX_ENABLED_BITS.
  */
 bool nvgpu_is_enabled(struct gk20a *g, u32 flag);
 
 /**
  * @brief Set the state of a flag.
  *
- * Set the state of the passed \a flag to \a state.
- * This is generally a somewhat low level operation with lots of potential
- * side effects. Be weary about where and when you use this. Typically a bunch
- * of calls to this early in the driver boot sequence makes sense (as
- * information is determined about the GPU at run time). Calling this in steady
- * state operation is probably an incorrect thing to do.
+ * Set the value of the passed \a flag to \a state.
+ * This is a low level operation with lots of potential side effects.
+ * Typically a bunch of calls to this early in the driver boot sequence makes
+ * sense (as information is determined about the GPU at run time). Calling this
+ * after GPU boot has completed is probably an incorrect thing to do.
+ * Invokes the function #nvgpu_set_bit() or #nvgpu_clear_bit() based on the
+ * value of \a state, and the parameters passed are \a flag and the variable
+ * \a enabled_flags in #gk20a. The caller of this function needs to ensure that
+ * the value of \a flag is less than #NVGPU_MAX_ENABLED_BITS.
  *
- * @param g [in]	The GPU.
- * @param flag [in]	Which flag to modify.
- * @param state [in]	The state to set the \a flag to.
+ * @param g [in] GPU super structure. Function does not perform any
+ *		 validation of this parameter.
+ * @param flag [in] Which flag to modify. Function validates if the value
+ *		    of this parameter is less than #NVGPU_MAX_ENABLED_BITS.
+ *		    If the value provided is not less than
+ *		    #NVGPU_MAX_ENABLED_BITS, the function returns without
+ *		    performing any operation.
+ * @param state [in] The state to set the \a flag to. Function does not
+ *		     perform any validation of this parameter.
  */
 void nvgpu_set_enabled(struct gk20a *g, u32 flag, bool state);
 
 /**
  * @brief Allocate the memory for the enabled flags.
  *
- * @param g [in]	The GPU superstructure.
+ * Allocates memory for the variable \a enabled_flags in #gk20a. Uses the
+ * wrapper macro to invoke the function #nvgpu_kzalloc_impl() to allocate
+ * the memory with \a g and the size required for allocation as parameters.
+ * Variable \a enabled_flags in struct #gk20a is a pointer to unsigned long,
+ * hence the size requested for allocation is equal to the size of number of
+ * unsigned long variables required to hold #NVGPU_MAX_ENABLED_BITS.
+ *
+ * @param g [in] GPU super structure. Function does not perform any
+ *		 validation of this parameter.
  *
  * @return 0 for success, < 0 for error.
  *
+ * @retval 0 for success.
  * @retval -ENOMEM if fails to allocate the necessary memory.
  */
 int nvgpu_init_enabled_flags(struct gk20a *g);
@@ -270,14 +296,18 @@ int nvgpu_init_enabled_flags(struct gk20a *g);
 /**
  * @brief Free the memory for the enabled flags. Called during driver exit.
  *
- * @param g [in]	The GPU superstructure.
+ * Calls the wrapper macro to invoke the function #nvgpu_kfree_impl() with
+ * \a g and variable \a enabled_flags in #gk20a as parameters.
+ *
+ * @param g [in] GPU super structure. Function does not perform any
+ *		 validation of this parameter.
  */
 void nvgpu_free_enabled_flags(struct gk20a *g);
 
 /**
  * @brief Print enabled flags value.
  *
- * @param g [in]	The GPU superstructure.
+ * @param g [in] The GPU superstructure.
  */
 void nvgpu_print_enabled_flags(struct gk20a *g);
 

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

@@ -41,9 +41,11 @@ struct nvgpu_ref {
  * @brief Initialize the reference object.
  *
  * Initializes the reference count of the object pointed by \a ref by
- * atomically setting it to 1.
+ * atomically setting it to 1. Invokes function #nvgpu_atomic_set with variable
+ * \a refcount in #nvgpu_ref and 1 as parameters to set the value atomically.
  *
- * @param ref [in]	The nvgpu_ref object to initialize.
+ * @param ref [in] The nvgpu_ref object to initialize. Function does not
+ *		   perform any validation of the parameter.
  */
 static inline void nvgpu_ref_init(struct nvgpu_ref *ref)
 {
@@ -51,11 +53,13 @@ static inline void nvgpu_ref_init(struct nvgpu_ref *ref)
 }
 
 /**
- * @brief Increment the reference count.
+ * @brief Atomically increment the reference count.
  *
- * Increment the reference count for the object atomically.
+ * Increment the reference count for the object atomically. Invokes function
+ * #nvgpu_atomic_inc with variable \a refcount in #nvgpu_ref as parameter.
  *
- * @param ref [in]	The nvgpu_ref object.
+ * @param ref [in] The nvgpu_ref object. Function does not perform any
+ *		   validation of the parameter.
  */
 static inline void nvgpu_ref_get(struct nvgpu_ref *ref)
 {
@@ -63,15 +67,17 @@ static inline void nvgpu_ref_get(struct nvgpu_ref *ref)
 }
 
 /**
- * @brief Decrement the reference count.
+ * @brief Atomically decrement the reference count.
  *
- * Decrement reference count for the object and call \a release if it becomes
- * zero.
+ * Decrement reference count for the object atomically and call \a release if
+ * it becomes zero. Invokes the function #nvgpu_atomic_sub_and_test with
+ * variable \a refcount in #nvgpu_ref as parameter to decrement atomically.
  *
- * @param ref[in]	The nvgpu_ref object.
- * @param release [in]	Pointer to the function that would be invoked to
- * 			clean up the object when the reference count becomes
- * 			zero.
+ * @param ref[in] The nvgpu_ref object. Function does not perform any
+ *		  validation of the parameter.
+ * @param release [in] Pointer to the function that would be invoked to clean
+ *		       up the object when the reference count becomes zero.
+ *		       Function uses the parameter only if it is not NULL.
  */
 static inline void nvgpu_ref_put(struct nvgpu_ref *ref,
 		void (*release)(struct nvgpu_ref *r))
@@ -84,18 +90,23 @@ static inline void nvgpu_ref_put(struct nvgpu_ref *ref,
 }
 
 /**
- * @brief Decrement reference count for the object, call release() if it
- * becomes zero and return the status of the removal.
+ * @brief Atomically decrement the reference count for the object and invoke
+ * the callback function if it becomes zero and return the status of the
+ * removal.
  *
- * Decrement the reference count for the object pointed by \a ref, invokes the
- * callback function \a release if it becomes zero and returns the status of
+ * Atomically decrement the reference count for the object pointed by \a ref
+ * using the function #nvgpu_atomic_sub_and_test. \a refcount in #nvgpu_ref is
+ * passed as the parameter to decrement atomically. Invokes the callback
+ * function \a release if the refcount becomes zero and returns the status of
  * the removal.
  *
- * @param ref [in]	The nvgpu_ref object.
- * @param release [in]	Pointer to the function that would be invoked to
- * 			clean up the object when the reference count becomes
- * 			zero, i.e. the last reference corresponding to this
- * 			object is removed.
+ * @param ref [in] The nvgpu_ref object. Function does not perform any
+ *		   validation of the parameter.
+ * @param release [in] Pointer to the function that would be invoked to
+ *		       clean up the object when the reference count becomes
+ *		       zero, i.e. the last reference corresponding to this
+ *		       object is removed. Function uses the parameter only if
+ *		       it is not NULL
  *
  * @return Return 1 if object was removed, otherwise return 0. The user should
  * not make any assumptions about the status of the object in the memory when
@@ -118,12 +129,14 @@ static inline int nvgpu_ref_put_return(struct nvgpu_ref *ref,
 }
 
 /**
- * @brief Increment reference count of the object unless it is zero.
+ * @brief Atomically increment reference count of the object unless it is zero.
  *
  * Increment the reference count of the object pointed by \a ref unless it
- * is zero.
+ * is zero. Invokes the function #nvgpu_atomic_add_unless with \a refcount in
+ * #nvgpu_ref as the parameter to set.
  *
- * @param ref [in]	The nvgpu_ref object.
+ * @param ref [in] The nvgpu_ref object. Function does not perform any
+ *		   validation of the parameter.
  *
  * @return Return non-zero if the increment succeeds, Otherwise return 0.
  */

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

@@ -38,9 +38,11 @@ struct nvgpu_list_node {
 /**
  * @brief Initialize a list node.
  *
- * @param node [in]     List node to initialize.
+ * Initializes a list node by setting the \a prev and \a next pointers
+ * in #nvgpu_list_node \a node to \a node itself.
  *
- * Initializes a list node by setting the prev and next pointer to itself.
+ * @param node [in] List node to initialize. Function does not perform
+ *		    any validation of the parameter.
  */
 static inline void nvgpu_init_list_node(struct nvgpu_list_node *node)
 {
@@ -53,8 +55,10 @@ static inline void nvgpu_init_list_node(struct nvgpu_list_node *node)
  *
  * Adds the node \a new_node to the head of the list pointed by \a head.
  *
- * @param node [in]     Node to be added.
- * @param head [in]     Head of the list.
+ * @param node [in] Node to be added. Function does not perform any
+ *		    validation of the parameter.
+ * @param head [in] Head of the list. Function does not perform any
+ *		    validation of the parameter.
  */
 static inline void nvgpu_list_add(struct nvgpu_list_node *new_node,
 					struct nvgpu_list_node *head)
@@ -70,9 +74,11 @@ static inline void nvgpu_list_add(struct nvgpu_list_node *new_node,
  *
  * Adds the node \a new_node to the tail of the list pointed by \a head.
  *
- * @param node [in]     Node to be added.
- * @param head [in]     Tail node of the list where the
- * 			addition has to be done.
+ * @param new_node [in]	Node to be added. Function does not perform any
+ *			validation of the parameter.
+ * @param head [in] Tail node of the list where the
+ *		    addition has to be done. Function does not perform any
+ *		    validation of the parameter.
  *
  */
 static inline void nvgpu_list_add_tail(struct nvgpu_list_node *new_node,
@@ -88,9 +94,11 @@ static inline void nvgpu_list_add_tail(struct nvgpu_list_node *new_node,
  * @brief Delete a node from the list.
  *
  * Deletes the node \a node from the list and initialize the node pointers to
- * point to itself.
+ * point to itself. Uses the function #nvgpu_init_list_node with \a node as
+ * parameter to initialize the node after deleting it from the list.
  *
- * @param node [in]     Condition variable to wait.
+ * @param node [in] Node to be deleted. Function does not perform any
+ *		    validation of the parameter.
  */
 static inline void nvgpu_list_del(struct nvgpu_list_node *node)
 {
@@ -104,7 +112,8 @@ static inline void nvgpu_list_del(struct nvgpu_list_node *node)
  *
  * Checks if the list pointed by \a head is empty or not.
  *
- * @param head [in]    Head node of the list to be checked.
+ * @param head [in] Head node of the list to be checked. Function does not
+ *		    perform any validation of the parameter.
  *
  * @return Boolean value to indicate the status of the list.
  *
@@ -120,10 +129,15 @@ static inline bool nvgpu_list_empty(struct nvgpu_list_node *head)
  * @brief Move a node from the list to head.
  *
  * Moves the node pointed by \a node to the head of the list pointed
- * by \a head.
+ * by \a head. Invokes the function #nvgpu_list_del with \a node as parameter
+ * to delete the node from the list first and then uses the function
+ * #nvgpu_list_add with \a node and \a head as parameters to add the node
+ * back in the list.
  *
- * @param node [in]     Node to move.
- * @param head [in]     Head of the list.
+ * @param node [in] Node to move. Function does not perform any validation
+ *		    of the parameter.
+ * @param head [in] Head of the list. Function does not perform any validation
+ *		    of the parameter.
  */
 static inline void nvgpu_list_move(struct nvgpu_list_node *node,
 					struct nvgpu_list_node *head)
@@ -136,10 +150,13 @@ static inline void nvgpu_list_move(struct nvgpu_list_node *node,
  * @brief Replace a node in the list.
  *
  * Replaces the node pointed by \a old_node with the node pointed
- * by \a new_node.
+ * by \a new_node. Uses the function #nvgpu_init_list_node with \a old_node
+ * as parameter to initialize the node after replacing it with the \a new_node.
  *
- * @param old_node [in]     Node to replace.
- * @param new_node [in]     Node to replace with.
+ * @param old_node [in]	Node to replace. Function does not perform any
+ *			validation of the parameter.
+ * @param new_node [in]	Node to replace with. Function does not perform any
+ *			validation of the parameter.
  */
 static inline void nvgpu_list_replace_init(struct nvgpu_list_node *old_node,
 					struct nvgpu_list_node *new_node)
@@ -181,7 +198,8 @@ static inline void nvgpu_list_replace_init(struct nvgpu_list_node *old_node,
 /**
  * @brief First entry from the list.
  *
- * Fetches the first entry from the list.
+ * Fetches the first entry from the list. Does not perform any validation of
+ * the macro parameters.
  *
  * @param ptr [in]	Pointer to the head.
  * @param type [in]	Type of the entry.
@@ -195,7 +213,8 @@ static inline void nvgpu_list_replace_init(struct nvgpu_list_node *old_node,
 /**
  * @brief Last entry from the list.
  *
- * Fetches the last entry from the list.
+ * Fetches the last entry from the list. Does not perform any validation of
+ * the macro parameters.
  *
  * @param ptr [in]	Pointer to list.
  * @param type [in]	Type of the entry.
@@ -209,7 +228,8 @@ static inline void nvgpu_list_replace_init(struct nvgpu_list_node *old_node,
 /**
  * @brief Loop through each entry in the list.
  *
- * Loops through each entry in the list.
+ * Loops through each entry in the list. Does not perform any validation of
+ * the macro parameters.
  *
  * @param pos [in, out] Entry node in the list.
  * @param head [in]	Pointer to the list.
@@ -225,7 +245,7 @@ static inline void nvgpu_list_replace_init(struct nvgpu_list_node *old_node,
  * @brief Safe loop through each entry in the list.
  *
  * Loops through each entry in the list and safe against removal of the list
- * entry.
+ * entry. Does not perform any validation of the macro parameters.
  *
  * @param pos [in, out]	Entry node in the list.
  * @param n [in, out]	Next node in the list.

drivers/gpu/nvgpu/include/nvgpu/rbtree.h

@@ -66,14 +66,16 @@ struct nvgpu_rbtree_node {
 /**
  * @brief Insert a new node into rbtree.
  *
- * @param new_node [in]	Pointer to new node.
- * @param root [in]	Pointer to root of tree
- *
  * - Find the correct location in the tree for this node based on its key value
  *   and insert it by updating the pointers.
  * - Rebalance tree.
  *
  * NOTE: Nodes with duplicate key_start and overlapping ranges are not allowed.
+ *
+ * @param new_node [in]	Pointer to new node. Function does not insert if this
+ *			parameter is a duplicate entry in the tree.
+ * @param root [in] Pointer to root of tree. Function does not perform any
+ *		    validation of the parameter.
  */
 void nvgpu_rbtree_insert(struct nvgpu_rbtree_node *new_node,
 		    struct nvgpu_rbtree_node **root);
@@ -81,12 +83,14 @@ void nvgpu_rbtree_insert(struct nvgpu_rbtree_node *new_node,
 /**
  * @brief Delete a node from rbtree.
  *
- * @param node [in]	Pointer to node to be deleted
- * @param root [in]	Pointer to root of tree
- *
  * - Update tree pointers to remove this node from tree while keeping its
  *   children.
  * - Rebalance tree.
+ *
+ * @param node [in] Pointer to node to be deleted. Function does not perform
+ *		    any validation of the parameter.
+ * @param root [in] Pointer to root of tree. Function does not perform any
+ *		    validation of the parameter.
  */
 void nvgpu_rbtree_unlink(struct nvgpu_rbtree_node *node,
 		    struct nvgpu_rbtree_node **root);
@@ -94,13 +98,17 @@ void nvgpu_rbtree_unlink(struct nvgpu_rbtree_node *node,
 /**
  * @brief Search for a given key in rbtree
  *
- * @param key_start [in]	Key to be searched in rbtree
- * @param node [out]		Node pointer to be returned
- * @param root [in]		Pointer to root of tree
+ * This API will match \a key_start against \a key_start in #nvgpu_rbtree_node
+ * for each node. In case of a hit, \a node points to a node with given key.
+ * In case of a miss, \a node is NULL.
  *
- * This API will match given key against key_start of each node.
- * In case of a hit, node points to a node with given key.
- * In case of a miss, node is NULL.
+ * @param key_start [in] Key to be searched in rbtree. Function does not
+ *			 perform any validation of the parameter.
+ * @param node [out] Node pointer to be returned. Function does not
+ *		     perform any validation of the parameter.
+ * @param root [in] Pointer to root of tree. Function checks if this
+ *		    parameter is NULL. In case of a NULL value, the output
+ *		    parameter \a node is populated as NULL.
  */
 void nvgpu_rbtree_search(u64 key_start, struct nvgpu_rbtree_node **node,
 			     struct nvgpu_rbtree_node *root);
@@ -108,14 +116,20 @@ void nvgpu_rbtree_search(u64 key_start, struct nvgpu_rbtree_node **node,
 /**
  * @brief Search a node with key falling in range
  *
- * @param key [in]	Key to be searched in rbtree
- * @param node [out]	Node pointer to be returned
- * @param root [in]	Pointer to root of tree
+ * This API will compare the given \a key with \a key_start and \a key_end in
+ * #nvgpu_rbtree_node for every node, and finds a node where \a key value
+ * falls within the range indicated by \a key_start and \a key_end in
+ * #nvgpu_rbtree_node.
+ * In case of a hit, \a node points to a node with given key.
+ * In case of a miss, \a node is NULL.
  *
- * This API will match given key and find a node where key value
- * falls within range of {start, end} keys.
- * In case of a hit, node points to a node with given key.
- * In case of a miss, node is NULL.
+ * @param key [in] Key to be searched in rbtree. Function does not perform
+ *		   any validation of the parameter.
+ * @param node [out] Node pointer to be returned. Function does not perform
+ *		     any validation of the parameter.
+ * @param root [in] Pointer to root of tree. Function checks if the parameter
+ *		    is NULL. In case of a NULL value, the output parameter \a
+ *		    node is populated as NULL.
  */
 void nvgpu_rbtree_range_search(u64 key,
 			       struct nvgpu_rbtree_node **node,
@@ -124,14 +138,19 @@ void nvgpu_rbtree_range_search(u64 key,
 /**
  * @brief Search a node with key lesser than given key
  *
- * @param key_start [in]	Key to be searched in rbtree
- * @param node [out]		Node pointer to be returned
- * @param root [in]		Pointer to root of tree
+ * This API will match the given \a key_start with \a key_start in
+ * #nvgpu_rbtree_node for every node and finds a node with highest
+ * key value lesser than given \a key_start.
+ * In case of a hit, \a node points to the node which matches the
+ * search criteria.
+ * In case of a miss, \a node is NULL.
  *
- * This API will match given key and find a node with highest
- * key value lesser than given key.
- * In case of a hit, node points to a node with given key.
- * In case of a miss, node is NULL.
+ * @param key_start [in] Key to be searched in rbtree. Function does not
+ *			 perform any validation of the parameter.
+ * @param node [out] Node pointer to be returned. Function does not
+ *		     perform any validation of the parameter.
+ * @param root [in] Pointer to root of tree. Function performs the search
+ *		    only if the parameter is not equal to NULL.
  */
 void nvgpu_rbtree_less_than_search(u64 key_start,
 			       struct nvgpu_rbtree_node **node,
@@ -140,13 +159,17 @@ void nvgpu_rbtree_less_than_search(u64 key_start,
 /**
  * @brief Enumerate tree starting at the node with specified value.
  *
- * @param key_start [in]	Key value to begin enumeration from
- * @param node [out]		Pointer to first node in the tree
- * @param root [in]		Pointer to root of tree
+ * This API returns \a node pointer pointing to first node in the rbtree to
+ * begin enumerating the tree. Call this API once per enumeration. Call
+ * #nvgpu_rbtree_enum_next to get the next node. \a node is returned as NULL
+ * in case if a valid node cannot be found in the tree.
  *
- * This API returns node pointer pointing to first node in the rbtree to begin
- * enumerating the tree. Call this API once per enumeration. Call
- * #nvgpu_rbtree_enum_next to get the next node.
+ * @param key_start [in] Key value to begin enumeration from. Function does
+ *			 not perform any validation of the parameter.
+ * @param node [out] Pointer to first node in the tree. Function does
+ *		     not perform any validation of the parameter.
+ * @param root [in] Pointer to root of tree. Function performs the
+ *		    enumeration only if the parameter is not NULL.
  */
 void nvgpu_rbtree_enum_start(u64 key_start,
 			struct nvgpu_rbtree_node **node,
@@ -161,7 +184,11 @@ void nvgpu_rbtree_enum_start(u64 key_start,
  *
  * @param node [in,out]	Pointer to current node is passed in.
  *			Pointer to next node in the tree is passed back.
- * @param root [in]	Pointer to root of tree
+ *			Function checks if this parameter is pointing to a
+ *			valid node and not NULL.
+ * @param root [in] Pointer to root of tree. Function checks if this parameter
+ *		    is NULL. The search operation is carried out only if the
+ *		    parameter is not NULL.
  */
 void nvgpu_rbtree_enum_next(struct nvgpu_rbtree_node **node,
 		       struct nvgpu_rbtree_node *root);

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

@@ -34,25 +34,33 @@ struct gk20a;
 /**
  * @brief Copy memory buffer
  *
- * Copy memory from source buffer to destination buffer.
+ * Copy memory from source buffer \a srcb to destination buffer \a destb.
+ * This function uses the library function \a memcpy internally.
  *
- * @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.
+ * @param destb [out] Buffer into which data is to be copied.
+ *		      Function does not perform validation of this parameter.
+ * @param srcb [in] Buffer from which data is to be copied.
+ *		    Function does not perform validation of this parameter.
+ * @param n [in] Number of bytes to copy from src buffer to dest buffer.
+ *		 Function does not perform validation of this parameter.
  */
 void nvgpu_memcpy(u8 *destb, const u8 *srcb, size_t n);
 
 /**
  * @brief Compare memory buffers
  *
- * 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.
+ * 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 \a b1 are less
+ * than \a b2 then a value less than zero is returned. If the contents of \a b1
+ * are greater than \a b2 then a value greater than zero is returned. This
+ * function uses the library function \a memcmp internally.
  *
- * @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.
+ * @param b1 [in] First buffer to use in memory comparison.
+ *		  Function does not perform validation of this parameter.
+ * @param b2 [in] Second buffer to use in memory comparison.
+ *		  Function does not perform validation of this parameter.
+ * @param n [in] Number of bytes to compare between two buffers.
+ *		 Function does not perform validation of this parameter.
  *
  * @return 0 if the comparison matches else a non-zero value is returned.
  *
@@ -67,13 +75,20 @@ int nvgpu_memcmp(const u8 *b1, const u8 *b2, size_t n);
 /**
  * @brief Formats u32 into null-terminated string
  *
- * Formats the integer variable \a value into a null terminated string.
+ * Formats the integer variable \a value into a null terminated string. Uses
+ * the function #nvgpu_safe_add_u32 to count the number of digits in the
+ * input parameter \a value. A local variable is passed as an input parameter
+ * to the function #nvgpu_safe_add_u32 to store the count of the digits.
  *
- * @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. Should be in the range
- *                      2 - 16, both inclusive.
+ * @param dst [in,out] Buffer to copy the value into.
+ *		       Function does not perform validation of this parameter.
+ * @param value [in] Value to be formatted into string.
+ *		     Function does not perform validation of this parameter.
+ * @param size [in] Size available in the destination buffer. Returns 0 If the
+ *		    size available is less than the length required to create a
+ *					NULL terminated string equivalent of \a value parameter.
+ * @param radix	[in] Radix value to be used. Should be in the range 2 - 16,both
+ *		     inclusive.
  *
  * @return Returns number of digits added to string (not including '\0') if
  * successful, else 0.
@@ -83,12 +98,14 @@ int nvgpu_memcmp(const u8 *b1, const u8 *b2, size_t n);
 int nvgpu_strnadd_u32(char *dst, const u32 value, size_t size, u32 radix);
 
 /**
- * @brief Check that memory address is word (4-byte) aligned.
+ * @brief Check if the memory address is word (4-byte) aligned.
  *
  * Checks if the provided address is word aligned or not.
  *
- * @param g [in]	struct gk20a.
- * @param addr [in]	Memory address.
+ * @param g [in] The GPU structure, struct gk20a.
+ *		 Function does not perform validation of this parameter.
+ * @param addr [in] Memory address. Checks if the parameter is aligned with 4
+ *		    bytes or not.
  *
  * @return Boolean value to indicate the alignment status of the address.
  *

drivers/gpu/nvgpu/include/nvgpu/utils.h

@@ -60,9 +60,12 @@
 /**
  * @brief Higher 32 bits from 64 bit.
  *
- * Returns the most significant 32 bits of the 64 bit input value.
+ * Returns the most significant 32 bits of the 64 bit input value. Invokes the
+ * function #nvgpu_safe_cast_u64_to_u32 with \a n right shifted by 32 as
+ * parameter.
  *
- * @param n [in]	Input value.
+ * @param n [in] Input value. Function does not perform any validation
+ *		 of the parameter.
  *
  * @return Most significant 32 bits of \a n.
  */
@@ -74,9 +77,12 @@ static inline u32 u64_hi32(u64 n)
 /**
  * @brief Lower 32 bits from 64 bit.
  *
- * Returns the least significant 32 bits of the 64 bit input value.
+ * Returns the least significant 32 bits of the 64 bit input value. Invokes the
+ * function #nvgpu_safe_cast_u64_to_u32 with higher 32 bits masked out \a n as
+ * parameter.
  *
- * @param n [in]	Input value.
+ * @param n [in] Input value. Function does not perform any validation of
+ *		 the parameter.
  *
  * @return Least significant 32 bits of \a n.
  */
@@ -90,8 +96,10 @@ static inline u32 u64_lo32(u64 n)
  *
  * Returns a 64 bit value by combining the two 32 bit input values.
  *
- * @param hi [in]	Higher 32 bits.
- * @param lo [in]	Lower 32 bits.
+ * @param hi [in] Higher 32 bits. Function does not perform any validation
+ *		  of the parameter.
+ * @param lo [in] Lower 32 bits. Function does not perform any validation
+ *		  of the parameter.
  *
  * @return 64 bit value of which the least significant 32 bits are \a lo and
  * most significant 32 bits are \a hi.
@@ -104,14 +112,17 @@ static inline u64 hi32_lo32_to_u64(u32 hi, u32 lo)
 /**
  * @brief Sets a particular field value in input data.
  *
- * Uses the \a mask value to clear the bits that are part of the field and
- * sets the value mentioned in \a field in those bit positions.
+ * Uses the \a mask value to clear those bit positions in \a val and the value
+ * of \a field is used to set the bits in the value to be returned.
  *
- * @param val [in]	Value to set the field in.
- * @param mask [in]	Mask for the field.
- * @param field [in]	Field value.
+ * @param val [in] Value to set the field in. Function does not perform any
+ *		   validation of the parameter.
+ * @param mask [in] Mask for the field. Function does not perform any
+ *		    validation of the parameter.
+ * @param field [in] Field value. Function does not perform any validation
+ *		     of the parameter.
  *
- * @return Returns \a val with updated field.
+ * @return Returns a value with updated bits.
  */
 static inline u32 set_field(u32 val, u32 mask, u32 field)
 {
@@ -121,10 +132,12 @@ static inline u32 set_field(u32 val, u32 mask, u32 field)
 /**
  * @brief Gets a particular field value from input data.
  *
- * Returns the field value at mask position in reg.
+ * Returns the field value at \a mask position in \a reg.
  *
- * @param reg [in]	Value to get the field from.
- * @param mask [in]	Mask for the field.
+ * @param reg [in] Value to get the field from. Function does not perform any
+ *		   validation of the parameter.
+ * @param mask [in] Mask for the field. Function does not perform any
+ *		    validation of the parameter.
  *
  * @return Field value from \a reg according to the \a mask.
  */

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

@@ -200,9 +200,11 @@ struct nvgpu_worker {
  *
  * This function returns true if the running status of the underlying worker
  * thread is set to zero. This indicates that the worker thread is no longer
- * running.
+ * running. Invokes the function #nvgpu_thread_should_stop() with variable
+ * \a poll_task in #nvgpu_worker struct passed as parameter.
  *
- * @param worker [in]	The worker
+ * @param worker [in] The worker struct. Function does not perform any validation
+ *		      of the parameter.
  *
  * @return Boolean value indicating if the thread should stop or not.
  *
@@ -218,9 +220,28 @@ bool nvgpu_worker_should_stop(struct nvgpu_worker *worker);
  * up immediately. If the work item already existed in the list, it's not added,
  * because in that case it has been scheduled already but has not yet been
  * processed.
+ * - Checks if the thread associated with \a poll_task in #nvgpu_worker is
+ *   already started. If not, try to start the thread. Return -1 if the thread
+ *   creation fails.
+ * - Function #nvgpu_spinlock_acquire() is called with variable \a
+ *   items_lock in #nvgpu_worker as parameter to acquire the lock before
+ *   trying to add the work item.
+ * - #nvgpu_list_empty is called with \a work_item as parameter to check if the
+ *   item is already added or not.
+ * - If the item is already added, invoke the function #nvgpu_spinlock_release
+ *   with variable \a items_lock in #nvgpu_worker as parameter to release the
+ *   lock, and return -1.
+ * - Invokes #nvgpu_list_add_tail with \a work_item and \a items in
+ *   #nvgpu_worker as parameters to add the work item, if it is not already
+ *   present in the list.
+ * - Function #nvgpu_spinlock_release() is invoked with variable \a items_lock
+ *   in #nvgpu_worker as parameter to release the lock acquired.
+ * The worker thread is woken up after the addition of the work item.
  *
- * @param worker [in]	The worker.
- * @param worker [in]	The work item for the worker to work on.
+ * @param worker [in] The worker. Function does not perform any validation
+ *		      of the parameter.
+ * @param worker [in] The work item for the worker to work on. Function does
+ *		      not perform any validation of the parameter.
  *
  * @return Integer value indicating the status of enqueue operation.
  *
@@ -234,9 +255,17 @@ int nvgpu_worker_enqueue(struct nvgpu_worker *worker,
  * @brief This API is used to initialize the worker with a name that's a
  * conjunction of the two parameters: {worker_name}_{gpu_name}.
  *
- * @param worker [in]		The worker.
- * @param worker_name [in]	The name of the worker.
- * @param gpu_name [in]		The name of the GPU.
+ * Uses the library function \a strncat to populate the variable \a thread_name
+ * in #nvgpu_worker. The input parameters \a worker_name and \a gpu_name are
+ * used as parameters to \a strncat in multiple stages to populate the name of
+ * the worker thread.
+ *
+ * @param worker [in] The worker. Function does not perform any
+ *		      validation of the parameter.
+ * @param worker_name [in] The name of the worker. Function does not perform
+ *			   any validation of the parameter.
+ * @param gpu_name [in] The name of the GPU. Function does not perform any
+ *			validation of the parameter.
  */
 void nvgpu_worker_init_name(struct nvgpu_worker *worker,
 		const char* worker_name, const char *gpu_name);
@@ -244,14 +273,36 @@ void nvgpu_worker_init_name(struct nvgpu_worker *worker,
 /**
  * @brief Initialize the worker's metadata and start the background thread.
  *
- * @param g [in]	The GPU superstructure.
- * @param worker [in]	The worker.
- * @param ops [in]	The worker ops specific for this worker.
+ * - Invokes the function #nvgpu_atomic_set with variable \a put in
+ *   #nvgpu_worker and 0 as parameters to initialize the atomic variable.
+ * - Invokes the function #nvgpu_cond_init() with variable \a wq in
+ *   #nvgpu_worker as parameter to initialize the condition variable.
+ * - Invokes the function #nvgpu_init_list_node with variable \a items in
+ *   #nvgpu_worker as parameter to initialize the list.
+ * - Invokes the function #nvgpu_spinlock_init() with variable \a items_lock in
+ *   #nvgpu_worker as parameter to initialize the spin lock.
+ * - Invokes the function #nvgpu_mutex_init() with variable \a start_lock in
+ *   #nvgpu_worker as parameter to initialize the mutex variable.
+ * - Starts the thread associated with the \a worker. #nvgpu_thread_create()
+ *   is the function used internally to create the worker thread, the
+ *   parameters passed are \a poll_task in #nvgpu_worker, \a worker, a static
+ *   callback function associated with the thread and \a thread_name in
+ *   #nvgpu_worker. Any error value from the function #nvgpu_thread_create()
+ *   is returned by this function as it is.
+ *  On a successful completion of this function, 0 is returned.
+ *
+ * @param g [in] The GPU super structure. Function does not perform any
+ *		 validation of the parameter.
+ * @param worker [in] The worker. Function does not perform any validation of
+ *		      the parameter.
+ * @param worker_ops [in] The worker ops specific for this worker. Function
+ *			  does not perform any validation of the parameter.
  *
  * @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 0 on success.
  * @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
@@ -261,9 +312,18 @@ int nvgpu_worker_init(struct gk20a *g, struct nvgpu_worker *worker,
 		const struct nvgpu_worker_ops *ops);
 
 /**
- * @brief Stop the background thread and cleanup the metadata in the worker.
+ * @brief Stop the background thread associated with the worker.
  *
- * @param worker [in]	The worker.
+ * - Invokes the function #nvgpu_mutex_acquire() with variable \a start_lock in
+ *   #nvgpu_worker as parameter to acquire the lock.
+ * - Invokes the function #nvgpu_thread_stop() with variable \a poll_task in
+ *   #nvgpu_worker as parameter to stop the poll task associated with the
+ *   worker.
+ * - Invokes the function #nvgpu_mutex_release() with variable \a start_lock in
+ *   #nvgpu_worker as parameter to release the lock.
+ *
+ * @param worker [in] The worker. Function does not perform any validation of
+ *		      the parameter.
  */
 void nvgpu_worker_deinit(struct nvgpu_worker *worker);