From e3dd17a2873cc83d567a71cf98ee54300218a5c2 Mon Sep 17 00:00:00 2001 From: ajesh Date: Thu, 5 Aug 2021 14:15:43 +0300 Subject: [PATCH] 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 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 Reviewed-by: Vaibhav Kachore Reviewed-by: Ankur Kishore Reviewed-by: mobile promotions GVS: Gerrit_Virtual_Submit Tested-by: mobile promotions --- drivers/gpu/nvgpu/include/nvgpu/enabled.h | 60 +++++++++++---- drivers/gpu/nvgpu/include/nvgpu/kref.h | 61 +++++++++------ drivers/gpu/nvgpu/include/nvgpu/list.h | 60 ++++++++++----- drivers/gpu/nvgpu/include/nvgpu/rbtree.h | 93 +++++++++++++++-------- drivers/gpu/nvgpu/include/nvgpu/string.h | 57 +++++++++----- drivers/gpu/nvgpu/include/nvgpu/utils.h | 43 +++++++---- drivers/gpu/nvgpu/include/nvgpu/worker.h | 84 +++++++++++++++++--- 7 files changed, 319 insertions(+), 139 deletions(-) diff --git a/drivers/gpu/nvgpu/include/nvgpu/enabled.h b/drivers/gpu/nvgpu/include/nvgpu/enabled.h index c4ea23e9f..33fcf2377 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/enabled.h +++ b/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); diff --git a/drivers/gpu/nvgpu/include/nvgpu/kref.h b/drivers/gpu/nvgpu/include/nvgpu/kref.h index fea67d8a3..a94bf90ad 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/kref.h +++ b/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. */ diff --git a/drivers/gpu/nvgpu/include/nvgpu/list.h b/drivers/gpu/nvgpu/include/nvgpu/list.h index 14ea6a920..2bed1b1e8 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/list.h +++ b/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. diff --git a/drivers/gpu/nvgpu/include/nvgpu/rbtree.h b/drivers/gpu/nvgpu/include/nvgpu/rbtree.h index 3eb0e20a8..1fc5292bd 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/rbtree.h +++ b/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); diff --git a/drivers/gpu/nvgpu/include/nvgpu/string.h b/drivers/gpu/nvgpu/include/nvgpu/string.h index 22a1a27b1..9b510e616 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/string.h +++ b/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. * diff --git a/drivers/gpu/nvgpu/include/nvgpu/utils.h b/drivers/gpu/nvgpu/include/nvgpu/utils.h index e59e6265e..20bfa7094 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/utils.h +++ b/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. */ diff --git a/drivers/gpu/nvgpu/include/nvgpu/worker.h b/drivers/gpu/nvgpu/include/nvgpu/worker.h index ee45466d7..2966282ce 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/worker.h +++ b/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);