diff --git a/drivers/gpu/nvgpu/include/nvgpu/kref.h b/drivers/gpu/nvgpu/include/nvgpu/kref.h index f5de10a64..fc50745a3 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/kref.h +++ b/drivers/gpu/nvgpu/include/nvgpu/kref.h @@ -31,34 +31,46 @@ #include struct nvgpu_ref { + /** + * Atomic reference count. + */ nvgpu_atomic_t refcount; }; -/* - * Initialize object. - * @ref: the nvgpu_ref object to initialize +/** + * @brief Initialize the reference object. + * + * @param ref [in] The nvgpu_ref object to initialize. + * + * Initializes the reference object pointed by \a ref. */ static inline void nvgpu_ref_init(struct nvgpu_ref *ref) { nvgpu_atomic_set(&ref->refcount, 1); } -/* +/** + * @brief Increment the reference count. + * + * @param ref [in] The nvgpu_ref object. + * * Increment reference count for the object - * @ref: the nvgpu_ref object */ static inline void nvgpu_ref_get(struct nvgpu_ref *ref) { nvgpu_atomic_inc(&ref->refcount); } -/* +/** + * @brief Decrement the reference count. + * + * @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. - * @ref: the nvgpu_ref object - * @release: 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. */ static inline void nvgpu_ref_put(struct nvgpu_ref *ref, void (*release)(struct nvgpu_ref *r)) @@ -70,15 +82,22 @@ static inline void nvgpu_ref_put(struct nvgpu_ref *ref, } } -/* - * Decrement reference count for the object, call release() if it becomes - * zero and return the status of the removal. - * @ref: the nvgpu_ref object - * @release: 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. - * 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 +/** + * @brief Decrement reference count for the object, call release() if it + * becomes zero and return 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 * further references to this object. */ @@ -94,10 +113,14 @@ static inline int nvgpu_ref_put_return(struct nvgpu_ref *ref, return 0; } -/* - * Increment reference count for the object unless it is zero. - * @ref: the nvgpu_ref object - * Return non-zero if the increment succeeds, Otherwise return 0. +/** + * @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 unless it is zero. + * + * @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 ab7f12a7c..e72d90376 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/list.h +++ b/drivers/gpu/nvgpu/include/nvgpu/list.h @@ -1,5 +1,5 @@ /* - * Copyright (c) 2017-2018, NVIDIA CORPORATION. All rights reserved. + * Copyright (c) 2017-2020, 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"), @@ -25,17 +25,39 @@ #include struct nvgpu_list_node { + /* + * Pointer to the previous node. + */ struct nvgpu_list_node *prev; + /* + * Pointer to the next node. + */ struct nvgpu_list_node *next; }; +/** + * @brief Initialize a list node. + * + * @param node [in] List node to initialize. + * + * Initializes a list node by setting the prev and next pointer to itself. + */ static inline void nvgpu_init_list_node(struct nvgpu_list_node *node) { node->prev = node; node->next = node; } -static inline void nvgpu_list_add(struct nvgpu_list_node *new_node, struct nvgpu_list_node *head) +/** + * @brief Add a new node to the list. + * + * @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) { new_node->next = head->next; new_node->next->prev = new_node; @@ -43,7 +65,17 @@ static inline void nvgpu_list_add(struct nvgpu_list_node *new_node, struct nvgpu head->next = new_node; } -static inline void nvgpu_list_add_tail(struct nvgpu_list_node *new_node, struct nvgpu_list_node *head) +/** + * @brief Add a new node to the tail of the list. + * + * @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) { new_node->prev = head->prev; new_node->prev->next = new_node; @@ -51,6 +83,14 @@ static inline void nvgpu_list_add_tail(struct nvgpu_list_node *new_node, struct head->prev = 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. + */ static inline void nvgpu_list_del(struct nvgpu_list_node *node) { node->prev->next = node->next; @@ -58,18 +98,47 @@ static inline void nvgpu_list_del(struct nvgpu_list_node *node) nvgpu_init_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. + * + * @return return true if the list is empty, otherwise return false. + */ static inline bool nvgpu_list_empty(struct nvgpu_list_node *head) { return head->next == head; } -static inline void nvgpu_list_move(struct nvgpu_list_node *node, 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. + */ +static inline void nvgpu_list_move(struct nvgpu_list_node *node, + struct nvgpu_list_node *head) { nvgpu_list_del(node); nvgpu_list_add(node, head); } -static inline void nvgpu_list_replace_init(struct nvgpu_list_node *old_node, struct nvgpu_list_node *new_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. + */ +static inline void nvgpu_list_replace_init(struct nvgpu_list_node *old_node, + struct nvgpu_list_node *new_node) { new_node->next = old_node->next; new_node->next->prev = new_node; @@ -78,23 +147,92 @@ static inline void nvgpu_list_replace_init(struct nvgpu_list_node *old_node, str nvgpu_init_list_node(old_node); } +/** @cond DOXYGEN_SHOULD_SKIP_THIS */ + +/** + * @brief Entry from the list + * + * @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) +/** + * @brief 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) \ nvgpu_list_entry((pos)->member.next, type, member) +/** @endcond DOXYGEN_SHOULD_SKIP_THIS */ + +/** + * @brief 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) \ nvgpu_list_entry((ptr)->next, type, member) +/** + * @brief 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) \ nvgpu_list_entry((ptr)->prev, type, member) +/** + * @brief Loop 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); \ &(pos)->member != (head); \ (pos) = nvgpu_list_next_entry(pos, type, member)) +/** + * @brief Safe loop through each entry in the list. + * + * @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), \ (n) = nvgpu_list_next_entry(pos, type, member); \ diff --git a/drivers/gpu/nvgpu/include/nvgpu/posix/circ_buf.h b/drivers/gpu/nvgpu/include/nvgpu/posix/circ_buf.h index 6b28421ff..b323c6321 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/posix/circ_buf.h +++ b/drivers/gpu/nvgpu/include/nvgpu/posix/circ_buf.h @@ -1,5 +1,5 @@ /* - * Copyright (c) 2018-2019, NVIDIA CORPORATION. All rights reserved. + * Copyright (c) 2018-2020, 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"), @@ -25,7 +25,31 @@ #include +/** + * @brief Return count in buffer. + * + * @param head [in] Head of the buffer. + * @param tail [in] Tail of the buffer. + * @param size [in] Max number of elements in buffer. + * + * Calculates the number of elements present in the circular buffer and + * returns the value. + * + * @return Count of elements in the buffer. + */ #define CIRC_CNT(head, tail, size) (((head) - (tail)) & ((size)-1U)) + +/** + * @brief Return space in buffer. + * + * @param head [in] Head of the buffer. + * @param tail [in] Tail of the buffer. + * @param size [in] Max number of elements in buffer. + * + * Calculates the space available in the circular buffer and returns the value. + * + * @return The space available in the buffer. + */ #define CIRC_SPACE(head, tail, size) CIRC_CNT((tail), ((head)+1U), (size)) #endif /* NVGPU_POSIX_CIRC_BUF_H */ diff --git a/drivers/gpu/nvgpu/include/nvgpu/posix/log2.h b/drivers/gpu/nvgpu/include/nvgpu/posix/log2.h index 3ad59fe7b..e63752137 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/posix/log2.h +++ b/drivers/gpu/nvgpu/include/nvgpu/posix/log2.h @@ -25,6 +25,16 @@ #include +/** + * @brief Integer logarithm for base 2. + * + * @param x [in] The number to get the log for. + * + * Calculates the log to the base 2 of input value \a x and returns the + * integer value of the same. + * + * @return Integer value of log to the base 2 of input \a x. + */ #define ilog2(x) ({ \ unsigned long fls_val = nvgpu_fls(x); \ \ @@ -33,6 +43,15 @@ fls_val; \ }) +/** + * @brief Round up to the power of two. + * + * @param x [in] Number to round up. + * + * Rounds up the input number \a x to power of two and returns. + * + * @return Input value \a x rounded up to the power of two. + */ #define roundup_pow_of_two(x) \ ({ \ unsigned long ret; \ @@ -46,6 +65,15 @@ ret; \ }) +/** + * @brief Round down to the power of two. + * + * @param x [in] Number to round down. + * + * Rounds down the input number \a x to power of two and returns. + * + * @return Input value \a x rounded down to the power of two. + */ #define rounddown_pow_of_two(x) \ ({ \ unsigned long ret; \ @@ -59,6 +87,15 @@ ret; \ }) +/** + * @brief Check for power of 2. + * + * @param x [in] Number to check. + * + * Checks if the input value \a x is a power of two or not. + * + * @return True if the input \a x is a power of two, else returns false. + */ #define is_power_of_2(x) \ (bool)({ \ typeof(x) __x__ = (x); \