From 394b0139117bf336fd5eb8b2944868b7df587b00 Mon Sep 17 00:00:00 2001 From: ajesh Date: Mon, 5 Apr 2021 09:44:55 +0300 Subject: [PATCH] gpu: nvgpu: address DVR comments for common.utils Address the issues in common.utils unit which came up in DVR. JIRA NVGPU-6595 Change-Id: I0573dc97cb33ab7f0618ed43fb60e9b950ccc086 Signed-off-by: ajesh Reviewed-on: https://git-master.nvidia.com/r/c/linux-nvgpu/+/2510296 (cherry picked from commit 3e8a049377d4f3b9ea6f41d9d21eca90bf374b52) Reviewed-on: https://git-master.nvidia.com/r/c/linux-nvgpu/+/2512609 Reviewed-by: svcacv Reviewed-by: Alex Waterman Reviewed-by: Vijayakumar Subbu Reviewed-by: mobile promotions GVS: Gerrit_Virtual_Submit Tested-by: mobile promotions --- drivers/gpu/nvgpu/include/nvgpu/enabled.h | 9 ++-- drivers/gpu/nvgpu/include/nvgpu/kref.h | 28 +++++------ drivers/gpu/nvgpu/include/nvgpu/list.h | 57 ++++++++++++----------- drivers/gpu/nvgpu/include/nvgpu/rbtree.h | 28 +++++------ drivers/gpu/nvgpu/include/nvgpu/string.h | 22 ++++----- drivers/gpu/nvgpu/include/nvgpu/utils.h | 24 +++++----- drivers/gpu/nvgpu/include/nvgpu/worker.h | 20 ++++---- 7 files changed, 94 insertions(+), 94 deletions(-) diff --git a/drivers/gpu/nvgpu/include/nvgpu/enabled.h b/drivers/gpu/nvgpu/include/nvgpu/enabled.h index 600a15882..066413268 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/enabled.h +++ b/drivers/gpu/nvgpu/include/nvgpu/enabled.h @@ -236,17 +236,16 @@ bool nvgpu_is_enabled(struct gk20a *g, u32 flag); /** * @brief Set the state of a flag. * - * @param g [in] The GPU. - * @param flag [in] Which flag to modify. - * @param state [in] The state to set the \a flag to. - * * 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. + * + * @param g [in] The GPU. + * @param flag [in] Which flag to modify. + * @param state [in] The state to set the \a flag to. */ void nvgpu_set_enabled(struct gk20a *g, u32 flag, bool state); diff --git a/drivers/gpu/nvgpu/include/nvgpu/kref.h b/drivers/gpu/nvgpu/include/nvgpu/kref.h index 921dcf263..fea67d8a3 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/kref.h +++ b/drivers/gpu/nvgpu/include/nvgpu/kref.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"), @@ -40,10 +40,10 @@ struct nvgpu_ref { /** * @brief Initialize the reference object. * - * @param ref [in] The nvgpu_ref object to initialize. - * * Initializes the reference count of the object pointed by \a ref by * atomically setting it to 1. + * + * @param ref [in] The nvgpu_ref object to initialize. */ static inline void nvgpu_ref_init(struct nvgpu_ref *ref) { @@ -53,9 +53,9 @@ static inline void nvgpu_ref_init(struct nvgpu_ref *ref) /** * @brief Increment the reference count. * - * @param ref [in] The nvgpu_ref object. - * * Increment the reference count for the object atomically. + * + * @param ref [in] The nvgpu_ref object. */ static inline void nvgpu_ref_get(struct nvgpu_ref *ref) { @@ -65,13 +65,13 @@ static inline void nvgpu_ref_get(struct nvgpu_ref *ref) /** * @brief Decrement the reference count. * + * Decrement reference count for the object and call \a release if it becomes + * zero. + * * @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. - * - * Decrement reference count for the object and call release() if it becomes - * zero. */ static inline void nvgpu_ref_put(struct nvgpu_ref *ref, void (*release)(struct nvgpu_ref *r)) @@ -87,16 +87,16 @@ 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. * + * 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 + * 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. * - * 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 - * the removal. - * * @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 * the function returns 0 and should only use it to know that there are no @@ -120,11 +120,11 @@ static inline int nvgpu_ref_put_return(struct nvgpu_ref *ref, /** * @brief Increment reference count of the object unless it is zero. * - * @param ref [in] The nvgpu_ref object. - * * Increment the reference count of the object pointed by \a ref unless it * is zero. * + * @param ref [in] The nvgpu_ref object. + * * @return Return non-zero if the increment succeeds, Otherwise return 0. */ static inline int nvgpu_ref_get_unless_zero(struct nvgpu_ref *ref) diff --git a/drivers/gpu/nvgpu/include/nvgpu/list.h b/drivers/gpu/nvgpu/include/nvgpu/list.h index 640704440..14ea6a920 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/list.h +++ b/drivers/gpu/nvgpu/include/nvgpu/list.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"), @@ -51,10 +51,10 @@ static inline void nvgpu_init_list_node(struct nvgpu_list_node *node) /** * @brief Add a new node to the list. * + * 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. - * - * Adds the node \a new_node to the head of the list pointed by \a head. */ static inline void nvgpu_list_add(struct nvgpu_list_node *new_node, struct nvgpu_list_node *head) @@ -68,11 +68,12 @@ static inline void nvgpu_list_add(struct nvgpu_list_node *new_node, /** * @brief Add a new node to the tail of the list. * + * 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. * - * Adds the node \a new_node to the tail of the list pointed by \a head. */ static inline void nvgpu_list_add_tail(struct nvgpu_list_node *new_node, struct nvgpu_list_node *head) @@ -86,10 +87,10 @@ static inline void nvgpu_list_add_tail(struct nvgpu_list_node *new_node, /** * @brief Delete a node from the list. * - * @param node [in] Condition variable to wait. - * * Deletes the node \a node from the list and initialize the node pointers to * point to itself. + * + * @param node [in] Condition variable to wait. */ static inline void nvgpu_list_del(struct nvgpu_list_node *node) { @@ -101,10 +102,10 @@ static inline void nvgpu_list_del(struct nvgpu_list_node *node) /** * @brief Check for empty list. * - * @param head [in] Head node of the list to be checked. - * * Checks if the list pointed by \a head is empty or not. * + * @param head [in] Head node of the list to be checked. + * * @return Boolean value to indicate the status of the list. * * @retval TRUE if list is empty. @@ -118,11 +119,11 @@ static inline bool nvgpu_list_empty(struct nvgpu_list_node *head) /** * @brief Move a node from the list to head. * - * @param node [in] Node to move. - * @param head [in] Head of the list. - * * Moves the node pointed by \a node to the head of the list pointed * by \a head. + * + * @param node [in] Node to move. + * @param head [in] Head of the list. */ static inline void nvgpu_list_move(struct nvgpu_list_node *node, struct nvgpu_list_node *head) @@ -134,11 +135,11 @@ static inline void nvgpu_list_move(struct nvgpu_list_node *node, /** * @brief Replace a node in the list. * - * @param old_node [in] Node to replace. - * @param new_node [in] Node to replace with. - * * Replaces the node pointed by \a old_node with the node pointed * by \a new_node. + * + * @param old_node [in] Node to replace. + * @param new_node [in] Node to replace with. */ static inline void nvgpu_list_replace_init(struct nvgpu_list_node *old_node, struct nvgpu_list_node *new_node) @@ -153,12 +154,12 @@ static inline void nvgpu_list_replace_init(struct nvgpu_list_node *old_node, /** * @brief Entry from the list * + * Uses token pasting operator to invoke the type and member specific + * function implementation. + * * @param ptr [in] Ptr to the list. * @param type [in] Type of the entry. * @param member [in] Name of the list entry in \a type. - * - * Uses token pasting operator to invoke the type and member specific - * function implementation. */ #define nvgpu_list_entry(ptr, type, member) \ type ## _from_ ## member(ptr) @@ -166,12 +167,12 @@ static inline void nvgpu_list_replace_init(struct nvgpu_list_node *old_node, /** * @brief Next entry from the list. * + * Fetches the next entry from the list. + * * @param pos [in] Position in the list to get the next entry from. * @param type [in] Type of the entry. * @param member [in] Name of the list entry in \a type. * - * Fetches the next entry from the list. - * * @return The next entry from the list. */ #define nvgpu_list_next_entry(pos, type, member) \ @@ -180,12 +181,12 @@ 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. + * * @param ptr [in] Pointer to the head. * @param type [in] Type of the entry. * @param member [in] Name of the list entry in \a type. * - * Fetches the first entry from the list. - * * @return The first entry from the list. */ #define nvgpu_list_first_entry(ptr, type, member) \ @@ -194,12 +195,12 @@ 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. + * * @param ptr [in] Pointer to list. * @param type [in] Type of the entry. * @param member [in] Name of the list entry in \a type. * - * Fetches the last entry from the list. - * * @return The last entry from the list. */ #define nvgpu_list_last_entry(ptr, type, member) \ @@ -208,12 +209,12 @@ 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. + * * @param pos [in, out] Entry node in the list. * @param head [in] Pointer to the list. * @param type [in] Type of the entry. * @param member [in] Name of the list entry in \a type. - * - * Loops through each entry in the list. */ #define nvgpu_list_for_each_entry(pos, head, type, member) \ for ((pos) = nvgpu_list_first_entry(head, type, member); \ @@ -223,14 +224,14 @@ 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. + * * @param pos [in, out] Entry node in the list. * @param n [in, out] Next node in the list. * @param head [in] Pointer to the list. * @param type [in] Type of the entry. * @param member [in] Name of the list entry in \a type. - * - * Loops safely through each entry in the list. For every iteration the next - * entry in the list is also fetched. */ #define nvgpu_list_for_each_entry_safe(pos, n, head, type, member) \ for ((pos) = nvgpu_list_first_entry(head, type, member), \ diff --git a/drivers/gpu/nvgpu/include/nvgpu/rbtree.h b/drivers/gpu/nvgpu/include/nvgpu/rbtree.h index 2571ab3e2..3eb0e20a8 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/rbtree.h +++ b/drivers/gpu/nvgpu/include/nvgpu/rbtree.h @@ -1,5 +1,5 @@ /* - * Copyright (c) 2017-2018, 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"), @@ -98,9 +98,9 @@ void nvgpu_rbtree_unlink(struct nvgpu_rbtree_node *node, * @param node [out] Node pointer to be returned * @param root [in] Pointer to root of tree * - * 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 + * 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. */ void nvgpu_rbtree_search(u64 key_start, struct nvgpu_rbtree_node **node, struct nvgpu_rbtree_node *root); @@ -113,9 +113,9 @@ void nvgpu_rbtree_search(u64 key_start, struct nvgpu_rbtree_node **node, * @param root [in] Pointer to root of tree * * 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 + * 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. */ void nvgpu_rbtree_range_search(u64 key, struct nvgpu_rbtree_node **node, @@ -129,9 +129,9 @@ void nvgpu_rbtree_range_search(u64 key, * @param root [in] Pointer to root of tree * * 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 + * 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. */ void nvgpu_rbtree_less_than_search(u64 key_start, struct nvgpu_rbtree_node **node, @@ -155,13 +155,13 @@ void nvgpu_rbtree_enum_start(u64 key_start, /** * @brief Find next node in enumeration in order by key value. * - * @param node [in,out] Pointer to current node is passed in. - * Poiner to next node in the tree is passed out. - * @param root [in] Pointer to root of tree - * * To get the next node in the tree, pass in the current \a node. This API * returns \a node pointer pointing to next node in the rbtree in order by key * value. + * + * @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 */ 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 97f528de0..a2505cc12 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/string.h +++ b/drivers/gpu/nvgpu/include/nvgpu/string.h @@ -1,5 +1,5 @@ /* - * Copyright (c) 2018-2019, 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"), @@ -34,26 +34,26 @@ struct gk20a; /** * @brief Copy memory buffer * + * Copy memory from source buffer to destination 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); /** * @brief Compare memory buffers * - * @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 \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. * + * @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. + * * @return 0 if the comparison matches else a non-zero value is returned. * * @retval 0 if both buffers match. @@ -67,13 +67,13 @@ 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. + * * @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. * @@ -84,11 +84,11 @@ int nvgpu_strnadd_u32(char *dst, const u32 value, size_t size, u32 radix); /** * @brief Check that 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. * - * 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. diff --git a/drivers/gpu/nvgpu/include/nvgpu/utils.h b/drivers/gpu/nvgpu/include/nvgpu/utils.h index 436bf6957..2e903f58f 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/utils.h +++ b/drivers/gpu/nvgpu/include/nvgpu/utils.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"), @@ -58,10 +58,10 @@ /** * @brief Higher 32 bits from 64 bit. * - * @param n [in] Input value. - * * Returns the most significant 32 bits of the 64 bit input value. * + * @param n [in] Input value. + * * @return Most significant 32 bits of \a n. */ static inline u32 u64_hi32(u64 n) @@ -72,10 +72,10 @@ static inline u32 u64_hi32(u64 n) /** * @brief Lower 32 bits from 64 bit. * - * @param n [in] Input value. - * * Returns the least significant 32 bits of the 64 bit input value. * + * @param n [in] Input value. + * * @return Least significant 32 bits of \a n. */ static inline u32 u64_lo32(u64 n) @@ -86,11 +86,11 @@ static inline u32 u64_lo32(u64 n) /** * @brief 64 bit from two 32 bit values. * + * 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. * - * Returns a 64 bit value by combining the two 32 bit input values. - * * @return 64 bit value of which the least significant 32 bits are \a lo and * most significant 32 bits are \a hi. */ @@ -102,13 +102,13 @@ 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. + * * @param val [in] Value to set the field in. * @param mask [in] Mask for the field. * @param field [in] Field value. * - * 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. - * * @return Returns \a val with updated field. */ static inline u32 set_field(u32 val, u32 mask, u32 field) @@ -119,11 +119,11 @@ 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. + * * @param reg [in] Value to get the field from. * @param mask [in] Mask for the field. * - * Returns the field value at mask position in reg. - * * @return Field value from \a reg according to the \a mask. */ static inline u32 get_field(u32 reg, u32 mask) diff --git a/drivers/gpu/nvgpu/include/nvgpu/worker.h b/drivers/gpu/nvgpu/include/nvgpu/worker.h index de8369731..ee45466d7 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/worker.h +++ b/drivers/gpu/nvgpu/include/nvgpu/worker.h @@ -1,5 +1,5 @@ /* - * Copyright (c) 2016-2019, NVIDIA CORPORATION. All rights reserved. + * Copyright (c) 2016-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"), @@ -111,7 +111,7 @@ struct nvgpu_worker_ops { /** * @brief This interface is used to pass any post processing callback * for the worker thread after wakeup. The worker thread executes this - * callback everytime before sleeping again. + * callback every time before sleeping again. * * Can be set to NULL if not applicable for this worker. * @@ -141,7 +141,7 @@ struct nvgpu_worker_ops { bool (*wakeup_condition)(struct nvgpu_worker *worker); /** - * @brief Used to pass any timeout condition for wakeup. + * @brief Used to pass any timeout value for wakeup. * * Can be set to NULL if not applicable for this worker. * @@ -198,11 +198,11 @@ struct nvgpu_worker { * @brief Generic check if the worker should stop because the thread stopped * running. * - * @param worker [in] The 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. * - * 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. + * @param worker [in] The worker * * @return Boolean value indicating if the thread should stop or not. * @@ -214,14 +214,14 @@ bool nvgpu_worker_should_stop(struct nvgpu_worker *worker); /** * @brief Append a work item to the worker's list. * - * @param worker [in] The worker. - * @param worker [in] The work item for the worker to work on. - * * This adds work item to the end of the list and wakes the 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. * + * @param worker [in] The worker. + * @param worker [in] The work item for the worker to work on. + * * @return Integer value indicating the status of enqueue operation. * * @retval 0 on success.