diff --git a/drivers/gpu/nvgpu/include/nvgpu/os_sched.h b/drivers/gpu/nvgpu/include/nvgpu/os_sched.h index b59cd92d6..f495d2d77 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/os_sched.h +++ b/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) diff --git a/drivers/gpu/nvgpu/include/nvgpu/posix/sizes.h b/drivers/gpu/nvgpu/include/nvgpu/posix/sizes.h index e296d563a..5dec87540 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/posix/sizes.h +++ b/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 */ diff --git a/drivers/gpu/nvgpu/include/nvgpu/posix/sort.h b/drivers/gpu/nvgpu/include/nvgpu/posix/sort.h index 60a5058fb..2e3d99141 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/posix/sort.h +++ b/drivers/gpu/nvgpu/include/nvgpu/posix/sort.h @@ -25,6 +25,18 @@ #include +/** + * @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)) diff --git a/drivers/gpu/nvgpu/include/nvgpu/posix/thread.h b/drivers/gpu/nvgpu/include/nvgpu/posix/thread.h index 9eff7508d..03be07b03 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/posix/thread.h +++ b/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); diff --git a/drivers/gpu/nvgpu/include/nvgpu/posix/types.h b/drivers/gpu/nvgpu/include/nvgpu/posix/types.h index 74d4c3834..a294d7714 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/posix/types.h +++ b/drivers/gpu/nvgpu/include/nvgpu/posix/types.h @@ -38,14 +38,44 @@ */ #include +/** + * 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 */ diff --git a/drivers/gpu/nvgpu/include/nvgpu/thread.h b/drivers/gpu/nvgpu/include/nvgpu/thread.h index 7605dbac0..02174779e 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/thread.h +++ b/drivers/gpu/nvgpu/include/nvgpu/thread.h @@ -33,71 +33,79 @@ #include /** - * 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); diff --git a/drivers/gpu/nvgpu/include/nvgpu/types.h b/drivers/gpu/nvgpu/include/nvgpu/types.h index f37e576bb..4f424597d 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/types.h +++ b/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