gpu: nvgpu: add Doxygen details for posix units

Add Doxygen documentation for the following posix units,
	-thread
	-types
	-sort
	-os_sched
	-sizes

Jira NVGPU-2596

Change-Id: I141e236ce136a28aacfad26c4fcbc551dc2c9084
Signed-off-by: ajesh <akv@nvidia.com>
Reviewed-on: https://git-master.nvidia.com/r/2198684
Reviewed-by: Automatic_Commit_Validation_User
GVS: Gerrit_Virtual_Submit
Reviewed-by: Philip Elcan <pelcan@nvidia.com>
Reviewed-by: Alex Waterman <alexw@nvidia.com>
Reviewed-by: mobile promotions <svcmobile_promotions@nvidia.com>
Tested-by: mobile promotions <svcmobile_promotions@nvidia.com>

drivers/gpu/nvgpu/include/nvgpu/os_sched.h

@@ -28,22 +28,46 @@
 struct gk20a;
 
 /**
- * nvgpu_current_tid - Query the id of current thread
+ * @brief Query the id of current thread.
  *
+ * @param g [in]	GPU driver struct.
+ *
+ * Shall return the thread id of the calling thread.
+ *
+ * @return Thread ID of the calling thread.
  */
 int nvgpu_current_tid(struct gk20a *g);
 
 /**
- * nvgpu_current_pid - Query the id of current process
+ * @brief Query the id of current process.
  *
+ * @param g [in]	GPU driver struct.
+ *
+ * Shall return the process id of the calling process.
+ *
+ * @return Process ID of the calling process.
  */
 int nvgpu_current_pid(struct gk20a *g);
 
+/**
+ * @brief Print the name of current thread.
+ *
+ * @param g [in]		GPU driver struct.
+ * @param func_name [in]	Calling function name.
+ * @param line [in]		Calling line number.
+ * @param ctx [in]		Context pointer.
+ * @param type [in]		Log level.
+ *
+ * Implements the printing of the current thread name along with the provided
+ * data. Implementation of this function is OS specific. For QNX, pthread
+ * name is printed along with other provided inputs. For POSIX build, pthread
+ * name is printed only if the build has support for GNU extensions which
+ * provides the thread name.
+ */
 void nvgpu_print_current_impl(struct gk20a *g, const char *func_name, int line,
 		void *ctx, enum nvgpu_log_type type);
 /**
- * nvgpu_print_current - print the name of current calling process
- *
+ * Print the name of calling thread.
  */
 #define nvgpu_print_current(g, ctx, type) \
 	nvgpu_print_current_impl(g, __func__, __LINE__, ctx, type)

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

@@ -23,20 +23,64 @@
 #ifndef NVGPU_POSIX_SIZES_H
 #define NVGPU_POSIX_SIZES_H
 
+/**
+ * Define for size equal to 0x100.
+ */
 #define SZ_256		256UL
 
+/**
+ * Define for size equal to 0x400(1K).
+ */
 #define SZ_1K		(1UL << 10)
+
+/**
+ * Define for size equal to 0x1000(4K).
+ */
 #define SZ_4K		(SZ_1K << 2)
+
+/**
+ * Define for size equal to 0x10000(64K).
+ */
 #define SZ_64K		(SZ_1K << 6)
+
+/**
+ * Define for size equal to 0x20000(128K).
+ */
 #define SZ_128K		(SZ_1K << 7)
 
+/**
+ * Define for size equal to 0x100000(1M).
+ */
 #define SZ_1M		(1UL << 20)
+
+/**
+ * Define for size equal to 0x1000000(16M).
+ */
 #define SZ_16M		(SZ_1M << 4)
+
+/**
+ * Define for size equal to 0x2000000(32M).
+ */
 #define SZ_32M		(SZ_1M << 5)
+
+/**
+ * Define for size equal to 0x10000000(256M).
+ */
 #define SZ_256M		(SZ_1M << 8)
+
+/**
+ * Define for size equal to 0x20000000(512M).
+ */
 #define SZ_512M		(SZ_1M << 9)
 
+/**
+ * Define for size equal to 0x40000000(1G).
+ */
 #define SZ_1G		(1UL << 30)
+
+/**
+ * Define for size equal to 0x100000000(4G).
+ */
 #define SZ_4G		(SZ_1G << 2)
 
 #endif /* NVGPU_POSIX_SIZES_H */

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

@@ -25,6 +25,18 @@
 
 #include <stdlib.h>
 
+/**
+ * @brief Sort a given set of data.
+ *
+ * @param base [in,out]		Pointer to the first element in the list.
+ * @param num [in]		Number of elements in the list pointed by base.
+ * @param size [in]		Size in bytes of each element in the list.
+ * @param cmp [in]		Function to compare two items in the list.
+ * @param swap [in]		Function to swap two items in the list.
+ *
+ * The function sorts the given set of data referenced by \a base. The internal
+ * implementation used for sorting is qsort.
+ */
 static void sort(void *base, size_t num, size_t size,
 		 int (*cmp)(const void *a, const void *b),
 		 void (*swap)(void *a, void *b, int n))

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

@@ -31,29 +31,73 @@
 /*
  * For some reason POSIX only allows 16 bytes of name length.
  */
+
+/**
+ * Maximum length for thread name.
+ */
 #define NVGPU_THREAD_POSIX_MAX_NAMELEN		16
 
+/**
+ * @brief Macro to push the thread cancellation cleanup handler.
+ *
+ * @param handler [in]	Handler to be called during cleanup.
+ * @param data [in]	Data to be passed as argument to the handler function.
+ *
+ * Pushes the specified cancellation cleanup handler routine onto the calling
+ * thread's cancellation cleanup stack.
+ */
 #define nvgpu_thread_cleanup_push(handler, data) \
 			pthread_cleanup_push(handler, data)
 
+/**
+ * @brief Macro to pop the thread cancellation cleanup handler.
+ */
 #define nvgpu_thread_cleanup_pop() pthread_cleanup_pop(1)
 
+/**
+ * Returns the PID of the calling process.
+ */
 #define nvgpu_getpid getpid
 
+/**
+ * Returns the Id of the calling thread.
+ */
 #define nvgpu_gettid pthread_self
-/*
+
+/**
  * Handles passing an nvgpu thread function into a posix thread.
  */
 struct nvgpu_posix_thread_data {
+	/**
+	 * NVGPU Function to be called from the main thread handler.
+	 */
 	int (*fn)(void *data);
+	/**
+	 * Data to be passed to the nvgpu thread function.
+	 */
 	void *data;
 };
 
 struct nvgpu_thread {
+	/**
+	 * Atomic variable to indicate thread running status.
+	 */
 	nvgpu_atomic_t running;
+	/**
+	 * Status variable to indicate whether the thread has to stop.
+	 */
 	bool should_stop;
+	/**
+	 * Thread identifier.
+	 */
 	pthread_t thread;
+	/**
+	 * Structure holding nvpgu specific thread details.
+	 */
 	struct nvgpu_posix_thread_data nvgpu;
+	/**
+	 * Name of the thread.
+	 */
 	char tname[NVGPU_THREAD_POSIX_MAX_NAMELEN];
 };
 
@@ -61,6 +105,20 @@ struct nvgpu_thread {
 struct nvgpu_posix_fault_inj *nvgpu_thread_get_fault_injection(void);
 #endif
 
+/**
+ * @brief Create a thread with specified priority.
+ *
+ * @param thread [in]		Thread to create.
+ * @param data [in]		Data to pass to threadfn.
+ * @param threadfn [in]		Thread function.
+ * @param priority [in]		Priority of the thread to be created.
+ * @param name [in]		Name of the thread.
+ *
+ * Create a thread with requested priority and run threadfn in it.
+ *
+ * @return Return 0 on success, else return the error number to indicate the
+ * error.
+ */
 int nvgpu_thread_create_priority(struct nvgpu_thread *thread,
 			void *data, int (*threadfn)(void *data),
 			int priority, const char *name);

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

@@ -38,14 +38,44 @@
  */
 #include <netinet/in.h>
 
+/**
+ * Alias for unsigned 8 bit char.
+ */
 typedef unsigned char		u8;
+
+/**
+ * Alias for unsigned 16 bit short.
+ */
 typedef unsigned short		u16;
+
+/**
+ * Alias for unsigned 32 bit int.
+ */
 typedef unsigned int		u32;
+
+/**
+ * Alias for unsigned 64 bit long long.
+ */
 typedef unsigned long long	u64;
 
+/**
+ * Alias for signed 8 bit char.
+ */
 typedef signed char		s8;
+
+/**
+ * Alias for signed 16 bit short.
+ */
 typedef signed short		s16;
+
+/**
+ * Alias for signed 32 bit int.
+ */
 typedef signed int		s32;
+
+/**
+ * Alias for signed 64 bit long long.
+ */
 typedef signed long long	s64;
 
 #endif /* NVGPU_POSIX_TYPES_H */

drivers/gpu/nvgpu/include/nvgpu/thread.h

@@ -33,71 +33,79 @@
 #include <nvgpu/utils.h>
 
 /**
- * nvgpu_thread_create - Create and run a new thread.
+ * @brief Create and run a new thread.
  *
- * @thread - thread structure to use
- * @data - data to pass to threadfn
- * @threadfn - Thread function
- * @name - name of the thread
+ * @param thread [in]	Thread structure to use.
+ * @param data [in]	Data to pass to threadfn.
+ * @param threadfn [in]	Thread function.
+ * @param name [in]	Name of the thread.
  *
  * Create a thread and run threadfn in it. The thread stays alive as long as
  * threadfn is running. As soon as threadfn returns the thread is destroyed.
+ * The threadfn needs to continuously poll #nvgpu_thread_should_stop() to
+ * determine if it should exit.
  *
- * threadfn needs to continuously poll nvgpu_thread_should_stop() to determine
- * if it should exit.
+ * @return Return 0 on success, otherwise returns error number to indicate the
+ * error.
  */
 int nvgpu_thread_create(struct nvgpu_thread *thread,
 		void *data,
 		int (*threadfn)(void *data), const char *name);
 
 /**
- * nvgpu_thread_stop - Destroy or request to destroy a thread
+ * @brief Stop a thread.
  *
- * @thread - thread to stop
+ * @param thread [in]	Thread to stop.
  *
- * Request a thread to stop by setting nvgpu_thread_should_stop() to
- * true and wait for thread to exit.
+ * A thread can be requested to stop by calling this function. This function
+ * places a request to cancel the corresponding thread by setting a status and
+ * waits until that thread exits.
  */
 void nvgpu_thread_stop(struct nvgpu_thread *thread);
 
 /**
- * nvgpu_thread_stop_graceful - Request a thread to be destroyed gracefully.
+ * @brief Request a thread to be stopped gracefully.
  *
- * @thread - thread to stop
- * @cb - callback function to trigger graceful exit
- * @data - thread data
+ * @param thread [in]		Thread to stop.
+ * @param thread_stop_fn [in]	Callback function to trigger graceful exit.
+ * @param data [in]		Thread data.
  *
- * Request a thread to stop by setting nvgpu_thread_should_stop() to
- * true and wait for thread to exit.
+ * Request a thread to stop by setting the status of the thread appropriately.
+ * In posix implementation, the callback function \a thread_stop_fn is invoked
+ * and waits till the thread exits.
  */
 void nvgpu_thread_stop_graceful(struct nvgpu_thread *thread,
 		void (*thread_stop_fn)(void *data), void *data);
 
 /**
- * nvgpu_thread_should_stop - Query if thread should stop
+ * @brief Query if thread should stop.
  *
- * @thread
+ * @param thread [in]	Thread to be queried for stop status.
  *
  * Return true if thread should exit. Can be run only in the thread's own
- * context and with the thread as parameter.
+ * context.
+ *
+ * @return TRUE if the thread has to stop, else FALSE.
  */
 bool nvgpu_thread_should_stop(struct nvgpu_thread *thread);
 
 /**
- * nvgpu_thread_is_running - Query if thread is running
+ * @brief Query if thread is running.
  *
- * @thread
+ * @param thread [in]	Thread to be queried for running status.
  *
- * Return true if thread is started.
+ * Returns a boolean value based on the current running status of the thread.
+ *
+ * @return TRUE if the current running status of the thread is 1, else FALSE.
  */
 bool nvgpu_thread_is_running(struct nvgpu_thread *thread);
 
 /**
- * nvgpu_thread_join - join a thread to reclaim resources
- * after it has exited
+ * @brief Join a thread to reclaim resources after it has exited.
  *
- * @thread - thread to join
+ * @param thread [in] - Thread to join.
  *
+ * The calling thread waits till the thread referenced by \a thread exits.
  */
 void nvgpu_thread_join(struct nvgpu_thread *thread);
 

drivers/gpu/nvgpu/include/nvgpu/types.h

@@ -53,29 +53,83 @@
  * overflows the 32 bit data type. So in this case we need an explicit cast to
  * 64 bits in order to prevent undefined behavior.
  */
+
+/**
+ * Type cast \a x to unsigned char.
+ */
 #define U8(x)	((u8)(x))
+
+/**
+ * Type cast \a x to unsigned short.
+ */
 #define U16(x)	((u16)(x))
+
+/**
+ * Type cast \a x to unsigned int.
+ */
 #define U32(x)	((u32)(x))
+
+/**
+ * Type cast \a x to unsigned long long.
+ */
 #define U64(x)	((u64)(x))
 
+/**
+ * Type cast \a x to signed char.
+ */
 #define S8(x)	((s8)(x))
+
+/**
+ * Type cast \a x to signed short.
+ */
 #define S16(x)	((s16)(x))
+
+/**
+ * Type cast \a x to signed int.
+ */
 #define S32(x)	((s32)(x))
+
+/**
+ * Type cast \a x to signed long long.
+ */
 #define S64(x)	((s64)(x))
 
 /* Linux uses U8_MAX, U32_MAX, etc instead of UCHAR_MAX, UINT32_MAX. We define
  * them here for non-Linux OSes
  */
 #if !defined(__KERNEL__) && !defined(U8_MAX)
+/**
+ * Maximum value for unsigned 8 bit.
+ */
 #define U8_MAX		U8(0xff)
+
+/**
+ * Maximum value for unsigned 16 bit.
+ */
 #define U16_MAX		U16(0xffff)
+
+/**
+ * Maximum value for unsigned 32 bit.
+ */
 #define U32_MAX		U32(~U32(0))
+
+/**
+ * Maximum value for unsigned 64 bit.
+ */
 #define U64_MAX		U64(~U64(0))
 #endif
 
 #if defined(__KERNEL__) && !defined(UCHAR_MAX)
 /* Linux doesn't define these max values, and we can't use limits.h */
+
+/**
+ * Maximum value for unsigned char.
+ */
 #define UCHAR_MAX U8_MAX
+
+/**
+ * Maximum value for signed char.
+ */
 #define SCHAR_MAX (U8_MAX/2)
 #endif