diff --git a/drivers/gpu/nvgpu/include/nvgpu/enabled.h b/drivers/gpu/nvgpu/include/nvgpu/enabled.h index b78ae3291..1bb23f7b6 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/enabled.h +++ b/drivers/gpu/nvgpu/include/nvgpu/enabled.h @@ -221,7 +221,10 @@ enum enum_enabled_flags { * @param g [in] The GPU. * @param flag [in] Which flag to check. * - * @retrun true if the passed \a flag is true; false otherwise. + * @return Boolean value to indicate the status of the bit. + * + * @retval TRUE if the flag bit is enabled. + * @retval FALSE if the flag bit is not enabled. */ bool nvgpu_is_enabled(struct gk20a *g, u32 flag); @@ -248,6 +251,7 @@ void nvgpu_set_enabled(struct gk20a *g, u32 flag, bool state); * @param g [in] The GPU superstructure. * * @return 0 for success, < 0 for error. + * * @retval -ENOMEM if fails to allocate the necessary memory. */ int nvgpu_init_enabled_flags(struct gk20a *g); diff --git a/drivers/gpu/nvgpu/include/nvgpu/kref.h b/drivers/gpu/nvgpu/include/nvgpu/kref.h index fc50745a3..921dcf263 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/kref.h +++ b/drivers/gpu/nvgpu/include/nvgpu/kref.h @@ -42,7 +42,8 @@ struct nvgpu_ref { * * @param ref [in] The nvgpu_ref object to initialize. * - * Initializes the reference object pointed by \a ref. + * Initializes the reference count of the object pointed by \a ref by + * atomically setting it to 1. */ static inline void nvgpu_ref_init(struct nvgpu_ref *ref) { @@ -54,7 +55,7 @@ static inline void nvgpu_ref_init(struct nvgpu_ref *ref) * * @param ref [in] The nvgpu_ref object. * - * Increment reference count for the object + * Increment the reference count for the object atomically. */ static inline void nvgpu_ref_get(struct nvgpu_ref *ref) { @@ -100,6 +101,9 @@ static inline void nvgpu_ref_put(struct nvgpu_ref *ref, * 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. + * + * @retval 1 if reference count becomes zero after decrement. + * @retval 0 if reference count is non-zero after decrement. */ static inline int nvgpu_ref_put_return(struct nvgpu_ref *ref, void (*release)(struct nvgpu_ref *r)) @@ -118,7 +122,8 @@ static inline int nvgpu_ref_put_return(struct nvgpu_ref *ref, * * @param ref [in] The nvgpu_ref object. * - * Increment the reference count of the object unless it is zero. + * Increment the reference count of the object pointed by \a ref unless it + * is zero. * * @return Return non-zero if the increment succeeds, Otherwise return 0. */ diff --git a/drivers/gpu/nvgpu/include/nvgpu/list.h b/drivers/gpu/nvgpu/include/nvgpu/list.h index e72d90376..640704440 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/list.h +++ b/drivers/gpu/nvgpu/include/nvgpu/list.h @@ -105,7 +105,10 @@ static inline void nvgpu_list_del(struct nvgpu_list_node *node) * * Checks if the list pointed by \a head is empty or not. * - * @return return true if the list is empty, otherwise return false. + * @return Boolean value to indicate the status of the list. + * + * @retval TRUE if list is empty. + * @retval FALSE if list is not empty. */ static inline bool nvgpu_list_empty(struct nvgpu_list_node *head) { @@ -147,8 +150,6 @@ static inline void nvgpu_list_replace_init(struct nvgpu_list_node *old_node, nvgpu_init_list_node(old_node); } -/** @cond DOXYGEN_SHOULD_SKIP_THIS */ - /** * @brief Entry from the list * @@ -176,8 +177,6 @@ static inline void nvgpu_list_replace_init(struct nvgpu_list_node *old_node, #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. * diff --git a/drivers/gpu/nvgpu/include/nvgpu/string.h b/drivers/gpu/nvgpu/include/nvgpu/string.h index be1700e4a..97f528de0 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/string.h +++ b/drivers/gpu/nvgpu/include/nvgpu/string.h @@ -32,45 +32,67 @@ struct gk20a; /** - * nvgpu_memcpy - Copy memory buffer + * @brief Copy memory buffer * - * @destb - Buffer into which data is to be copied. - * @srcb - Buffer from which data is to be copied. - * @n - Number of bytes to copy from src buffer to dest 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); /** - * nvgpu_memcmp - Compare memory buffers + * @brief Compare memory buffers * - * @b1 - First buffer to use in memory comparison. - * @b2 - Second buffer to use in memory comparison. - * @n - Number of bytes to compare between buffer1 and buffer2. + * @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 n bytes of two memory buffers. If the contents of the + * 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. + * + * @return 0 if the comparison matches else a non-zero value is returned. + * + * @retval 0 if both buffers match. + * @retval <0 if object pointed to by \a b1 is less than the object pointed to + * by \a b2. + * @retval >0 if object pointed to by \a b1 is greater than the object pointed + * to by \a b2. */ int nvgpu_memcmp(const u8 *b1, const u8 *b2, size_t n); /** - * nvgpu_strnadd_u32 - formats u32 into null-terminated string + * @brief Formats u32 into null-terminated string * - * Returns number of digits added to string (not including '\0') - * Returns 0 in case of invalid dst or radix, or insufficient space. - * Returns 0 if there was no room to add '\0' + * @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. + * + * @retval 0 in case of invalid radix or insufficient space. */ int nvgpu_strnadd_u32(char *dst, const u32 value, size_t size, u32 radix); /** - * nvgpu_mem_is_word_aligned - Check that memory address is word (4-byte) - * aligned. + * @brief Check that memory address is word (4-byte) aligned. * - * @g - struct gk20a. - * @addr - memory address. + * @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. + * @retval FALSE if \a addr is not word aligned. */ bool nvgpu_mem_is_word_aligned(struct gk20a *g, u8 *addr); diff --git a/drivers/gpu/nvgpu/include/nvgpu/worker.h b/drivers/gpu/nvgpu/include/nvgpu/worker.h index 0c7340cf1..de8369731 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/worker.h +++ b/drivers/gpu/nvgpu/include/nvgpu/worker.h @@ -200,11 +200,14 @@ struct nvgpu_worker { * * @param worker [in] The worker * - * @return true if the worker should stop. false otherwise. - * * 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. + * + * @return Boolean value indicating if the thread should stop or not. + * + * @retval TRUE if the worker thread should stop. + * @retval FALSE if the worker thread can continue running. */ bool nvgpu_worker_should_stop(struct nvgpu_worker *worker); @@ -219,7 +222,10 @@ bool nvgpu_worker_should_stop(struct nvgpu_worker *worker); * because in that case it has been scheduled already but has not yet been * processed. * - * @return 0 if successfully added, < 0 value on error. + * @return Integer value indicating the status of enqueue operation. + * + * @retval 0 on success. + * @retval -1 on failure. */ int nvgpu_worker_enqueue(struct nvgpu_worker *worker, struct nvgpu_list_node *work_item); @@ -242,7 +248,14 @@ void nvgpu_worker_init_name(struct nvgpu_worker *worker, * @param worker [in] The worker. * @param ops [in] The worker ops specific for this worker. * - * @return 0 for success, < 0 for error. + * @return 0 for success, < 0 for error. This function internally invokes + * the thread creation API for worker thread. The error codes generated by the + * thread creation API will be returned by this function. + * + * @retval EINVAL invalid thread attribute object. + * @retval EAGAIN insufficient system resources to create thread. + * @retval EFAULT error occurred trying to access the buffers or the + * start routine provided for thread creation. */ int nvgpu_worker_init(struct gk20a *g, struct nvgpu_worker *worker, const struct nvgpu_worker_ops *ops); @@ -254,4 +267,4 @@ int nvgpu_worker_init(struct gk20a *g, struct nvgpu_worker *worker, */ void nvgpu_worker_deinit(struct nvgpu_worker *worker); -#endif /* NVGPU_WORKER_H */ \ No newline at end of file +#endif /* NVGPU_WORKER_H */