gpu: nvgpu: add doxygen documentation

Add Doxygen documentation for the below units
 - log2
 - circ_buf
 - kref
 - list

Jira NVGPU-4417

Change-Id: I93d19a41ab4539cac0ccf514e790c6bb3f85bcc9
Signed-off-by: ajesh <akv@nvidia.com>
Reviewed-on: https://git-master.nvidia.com/r/c/linux-nvgpu/+/2286888
Reviewed-by: Philip Elcan <pelcan@nvidia.com>
Reviewed-by: Deepak Nibade <dnibade@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/kref.h

@@ -31,34 +31,46 @@
 #include <nvgpu/utils.h>
 
 struct nvgpu_ref {
+	/**
+	 * Atomic reference count.
+	 */
 	nvgpu_atomic_t refcount;
 };
 
-/*
+/**
- * Initialize object.
+ * @brief Initialize the reference object.
- * @ref: the nvgpu_ref object to initialize
+ *
+ * @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
+ * @brief Decrement reference count for the object, call release() if it
- * zero and return the status of the removal.
+ * 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
+ * @param ref [in]	The nvgpu_ref object.
- *	object when the reference count becomes zero, i.e. the last
+ * @param release [in]	Pointer to the function that would be invoked to
- *	reference corresponding to this object is removed.
+ * 			clean up the object when the reference count becomes
- * Return 1 if object was removed, otherwise return 0. The user should not
+ * 			zero, i.e. the last reference corresponding to this
- * make any assumptions about the status of the object in the memory when
+ * 			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.
+ * @brief Increment reference count of the object unless it is zero.
- * @ref: the nvgpu_ref object
+ *
- * Return non-zero if the increment succeeds, Otherwise return 0.
+ * @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)
 {

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 <nvgpu/types.h>
 
 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);	\

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 <nvgpu/bug.h>
 
+/**
+ * @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 */

drivers/gpu/nvgpu/include/nvgpu/posix/log2.h

@@ -25,6 +25,16 @@
 
 #include <nvgpu/bitops.h>
 
+/**
+ * @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);					\