From 4de7b8bbd120f4df98ac4777be1c30cb99c1a14c Mon Sep 17 00:00:00 2001 From: Vedashree Vidwans Date: Thu, 7 Jan 2021 10:20:02 -0800 Subject: [PATCH] gpu: nvgpu: update doxygen for common.fifo Modify doxygen comments - to add more information - correct spelling mistakes - update formatting Jira NVGPU-6179 Signed-off-by: Vedashree Vidwans Change-Id: If0a075b8875c8f5aee1d9710e7348e843a457534 Reviewed-on: https://git-master.nvidia.com/r/c/linux-nvgpu/+/2467530 (cherry picked from commit b367d3d0ea7f92b722aebdc8cf6018979fe74c47) Reviewed-on: https://git-master.nvidia.com/r/c/linux-nvgpu/+/2480583 GVS: Gerrit_Virtual_Submit Tested-by: mobile promotions Reviewed-by: Alex Waterman Reviewed-by: mobile promotions --- drivers/gpu/nvgpu/include/nvgpu/channel.h | 11 ++--- .../nvgpu/include/nvgpu/channel_user_syncpt.h | 12 +++--- .../gpu/nvgpu/include/nvgpu/engine_status.h | 14 +++--- drivers/gpu/nvgpu/include/nvgpu/engines.h | 4 +- drivers/gpu/nvgpu/include/nvgpu/fifo.h | 13 +----- drivers/gpu/nvgpu/include/nvgpu/gops/fifo.h | 9 ++-- .../gpu/nvgpu/include/nvgpu/pbdma_status.h | 8 ++-- drivers/gpu/nvgpu/include/nvgpu/runlist.h | 3 +- drivers/gpu/nvgpu/include/nvgpu/tsg.h | 43 +++++++++++-------- 9 files changed, 59 insertions(+), 58 deletions(-) diff --git a/drivers/gpu/nvgpu/include/nvgpu/channel.h b/drivers/gpu/nvgpu/include/nvgpu/channel.h index 39ad1f8f2..f4f460033 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/channel.h +++ b/drivers/gpu/nvgpu/include/nvgpu/channel.h @@ -1,5 +1,5 @@ /* - * Copyright (c) 2018-2020, NVIDIA CORPORATION. All rights reserved. + * Copyright (c) 2018-2021, 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"), @@ -323,7 +323,7 @@ struct nvgpu_channel { #if GK20A_CHANNEL_REFCOUNT_TRACKING /** * Ring buffer for most recent refcount gets and puts. Protected by - * ref_actions_lock when getting or putting refs (i.e., adding + * #ref_actions_lock when getting or putting refs (i.e., adding * entries), and when reading entries. */ struct nvgpu_channel_ref_action ref_actions[ @@ -383,6 +383,7 @@ struct nvgpu_channel { struct nvgpu_mem usermode_userd; /** GPFIFO memory for usermode submit. */ struct nvgpu_mem usermode_gpfifo; + /** Channel instance block memory. */ struct nvgpu_mem inst_block; /** @@ -523,7 +524,7 @@ struct nvgpu_channel { /** * If enabled, USERD and GPFIFO buffers are handled in userspace. * Userspace writes a submit token to the doorbell register in the - * usermode region to notify the GPU for new work on this channel. + * usermode region to notify the GPU of new work on this channel. * Usermode and kernelmode submit modes are mutually exclusive. * On usermode submit channels, the caller must keep track of GPFIFO * usage. The recommended way for the current hardware (Maxwell..Turing) @@ -966,8 +967,8 @@ int nvgpu_channel_setup_bind(struct nvgpu_channel *c, * @param ch [in] Channel pointer (must be non-NULL). * @param add [in] True to add a channel, false to remove it. * - * When #add is true, adds #ch to runlist. - * When #add is false, removes #ch from runlist. + * When \a add is true, adds \a c to runlist. + * When \a add is false, removes \a c from runlist. * * Function waits until H/W is done transitionning to the new runlist. * diff --git a/drivers/gpu/nvgpu/include/nvgpu/channel_user_syncpt.h b/drivers/gpu/nvgpu/include/nvgpu/channel_user_syncpt.h index 7362cb4e1..506b70f93 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/channel_user_syncpt.h +++ b/drivers/gpu/nvgpu/include/nvgpu/channel_user_syncpt.h @@ -1,5 +1,5 @@ /* - * Copyright (c) 2020, NVIDIA CORPORATION. All rights reserved. + * Copyright (c) 2020-2021, 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"), @@ -35,10 +35,10 @@ struct nvgpu_channel_user_syncpt; * * @param c [in] Pointer to Channel. * - * Construct a nvgpu_channel_user_syncpt that represents a syncpoint allocation + * Construct a #nvgpu_channel_user_syncpt that represents a syncpoint allocation * to be managed by userspace in conjunction with usermode submits. * - * @return Pointer to nvgpu_channel_user_syncpt in case of success, or NULL in + * @return Pointer to #nvgpu_channel_user_syncpt in case of success, or NULL in * case of failure. */ struct nvgpu_channel_user_syncpt * @@ -58,8 +58,8 @@ u32 nvgpu_channel_user_syncpt_get_id(struct nvgpu_channel_user_syncpt *s); * * @param s [in] User syncpoint pointer. * - * Get syncpoint GPU VA. This address can be used in push buffer entries - * for acquire/release operations. + * This function returns syncpoint GPU VA. This address can be used in push + * buffer entries for acquire/release operations. * * @return Syncpoint address (GPU VA) of syncpoint or 0 if not supported */ @@ -80,7 +80,7 @@ void nvgpu_channel_user_syncpt_set_safe_state(struct nvgpu_channel_user_syncpt * * * @param s [in] User syncpoint pointer. * - * Free the resources allocated by nvgpu_channel_user_syncpt_create. + * Free the resources allocated by #nvgpu_channel_user_syncpt_create. */ void nvgpu_channel_user_syncpt_destroy(struct nvgpu_channel_user_syncpt *s); diff --git a/drivers/gpu/nvgpu/include/nvgpu/engine_status.h b/drivers/gpu/nvgpu/include/nvgpu/engine_status.h index ae865640a..8f48dfa66 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/engine_status.h +++ b/drivers/gpu/nvgpu/include/nvgpu/engine_status.h @@ -1,5 +1,5 @@ /* - * Copyright (c) 2019-2020, NVIDIA CORPORATION. All rights reserved. + * Copyright (c) 2019-2021, 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"), @@ -68,7 +68,9 @@ #define ENGINE_STATUS_CTX_NEXT_ID_INVALID ENGINE_STATUS_CTX_ID_INVALID enum nvgpu_engine_status_ctx_status { - /** Context is not loaded on engine. Both id and next_id are invalid. */ + /** + * Context is not loaded on engine. Both id and next_id are invalid. + */ NVGPU_CTX_STATUS_INVALID, /** * Context is loaded on the engine. id field of engine_status @@ -106,20 +108,20 @@ struct nvgpu_engine_status_info { u32 ctx_id; /** Ctx_status field of engine_status h/w register. */ u32 ctxsw_state; - /** Specifies whether ctx_id is of channel or tsg type. */ + /** Specifies whether #ctx_id is of channel or tsg type. */ u32 ctx_id_type; /** Channel or tsg id that will be assigned to the engine. */ u32 ctx_next_id; - /** Specifies whether ctx_next_id is of channel or tsg type. */ + /** Specifies whether #ctx_next_id is of channel or tsg type. */ u32 ctx_next_id_type; /** - * Field, is_faulted is applicable for ce engine only and should be + * Field #is_faulted is applicable for ce engine only and should be * ignored for other types of engines. This is set when host * receives a fault message from ce engine. */ bool is_faulted; /** - * Field, is_busy is set if engine is not idle. Host will report + * Field #is_busy is set if engine is not idle. Host will report * non-idle if Host is about to send methods as well as when a context * request is outstanding to the engine, even when the engine itself is * idle. diff --git a/drivers/gpu/nvgpu/include/nvgpu/engines.h b/drivers/gpu/nvgpu/include/nvgpu/engines.h index 2a79c903b..f363d02b8 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/engines.h +++ b/drivers/gpu/nvgpu/include/nvgpu/engines.h @@ -1,5 +1,5 @@ /* - * Copyright (c) 2019-2020, NVIDIA CORPORATION. All rights reserved. + * Copyright (c) 2019-2021, 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"), @@ -53,7 +53,7 @@ struct nvgpu_device; enum nvgpu_fifo_engine { /** GR engine enum */ NVGPU_ENGINE_GR = 0U, - /** GR ce engine enum */ + /** GR CE engine enum */ NVGPU_ENGINE_GRCE = 1U, /** Async CE engine enum */ NVGPU_ENGINE_ASYNC_CE = 2U, diff --git a/drivers/gpu/nvgpu/include/nvgpu/fifo.h b/drivers/gpu/nvgpu/include/nvgpu/fifo.h index 255de0ba9..0dbcfc098 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/fifo.h +++ b/drivers/gpu/nvgpu/include/nvgpu/fifo.h @@ -317,7 +317,7 @@ struct nvgpu_fifo { struct nvgpu_list_node free_chs; /** * Lock used to read and update #free_chs list. Channel entry is - * removed when a channel is openend and added back to the #free_ch list + * removed when a channel is opened and added back to the #free_ch list * when channel is closed by userspace. * This lock is also used to protect #used_channels. */ @@ -337,7 +337,7 @@ struct nvgpu_fifo { struct nvgpu_tsg *tsg; /** * Lock used to read and update #nvgpu_tsg.in_use. TSG entry is - * in use when a TSG is openend and not in use when TSG is closed + * in use when a TSG is opened and not in use when TSG is closed * by userspace. Refer #nvgpu_tsg.in_use in tsg.h. */ struct nvgpu_mutex tsg_inuse_mutex; @@ -377,13 +377,6 @@ struct nvgpu_fifo { /** H/w specific recoverable PBDMA interrupts. */ u32 restartable_0; } pbdma; - - /** Engine interrupt specific data. */ - struct { - - } engine; - - } intr; #ifdef CONFIG_NVGPU_DEBUGGER @@ -454,7 +447,6 @@ int nvgpu_fifo_setup_sw(struct gk20a *g); * * @param g [in] The GPU driver struct. * - * Initialize FIFO software context: * - Init mutexes needed by FIFO module. Refer #nvgpu_fifo struct. * - Do #nvgpu_channel_setup_sw. * - Do #nvgpu_tsg_setup_sw. @@ -485,7 +477,6 @@ void nvgpu_fifo_cleanup_sw(struct gk20a *g); * * @param g [in] The GPU driver struct. * - * Clean up FIFO software context and related resources: * - Do userd.cleanup_sw. * - Do #nvgpu_channel_cleanup_sw. * - Do #nvgpu_tsg_cleanup_sw. diff --git a/drivers/gpu/nvgpu/include/nvgpu/gops/fifo.h b/drivers/gpu/nvgpu/include/nvgpu/gops/fifo.h index 8d1da6625..0905e55fd 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/gops/fifo.h +++ b/drivers/gpu/nvgpu/include/nvgpu/gops/fifo.h @@ -1,5 +1,5 @@ /* - * Copyright (c) 2019-2020, NVIDIA CORPORATION. All rights reserved. + * Copyright (c) 2019-2021, 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"), @@ -41,7 +41,7 @@ struct gops_fifo { * @param g [in] Pointer to GPU driver struct. * * This HAL is used to initialize FIFO software context, - * then do GPU h/w initializations. It always maps to + * then perform GPU h/w initializations. It always maps to * #nvpgu_fifo_init_support, except for vgpu case. * * @return 0 in case of success, < 0 in case of failure. @@ -71,7 +71,6 @@ struct gops_fifo { * @param g [in] Pointer to GPU driver struct. * @param tsg [in] Pointer to TSG struct. * - * Preempt TSG: * - Acquire lock for active runlist. * - Write h/w register to trigger TSG preempt for \a tsg. * - Preemption mode (e.g. CTA or WFI) depends on the preemption @@ -83,7 +82,7 @@ struct gops_fifo { * On some chips, it is also needed to disable scheduling * before preempting TSG. * - * @see nvgpu_preempt_get_timeout + * @see #nvgpu_preempt_get_timeout * @see nvgpu_gr_ctx::compute_preempt_mode * * @return 0 in case preemption succeeded, < 0 in case of failure. @@ -97,7 +96,7 @@ struct gops_fifo { * * @param g [in] Pointer to GPU driver struct. * - * Enable and configure h/w settings for FIFO: + * Reset FIFO unit and configure FIFO h/w settings. * - Enable PMC FIFO. * - Configure clock gating: * - Set SLCG settings for CE2 and FIFO. diff --git a/drivers/gpu/nvgpu/include/nvgpu/pbdma_status.h b/drivers/gpu/nvgpu/include/nvgpu/pbdma_status.h index 519afa7d5..95c9e78ae 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/pbdma_status.h +++ b/drivers/gpu/nvgpu/include/nvgpu/pbdma_status.h @@ -1,5 +1,5 @@ /* - * Copyright (c) 2019, NVIDIA CORPORATION. All rights reserved. + * Copyright (c) 2019-2021, 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"), @@ -64,7 +64,7 @@ #define PBDMA_STATUS_NEXT_ID_INVALID PBDMA_STATUS_ID_INVALID enum nvgpu_pbdma_status_chsw_status { - /** Channel is not loaded on pbdma. Both id and next_id are invalid */ + /** Channel is not loaded on pbdma. Both id and next_id are invalid. */ NVGPU_PBDMA_CHSW_STATUS_INVALID, /** * Channel is loaded on the pbdma. id field of pbdma_status @@ -96,11 +96,11 @@ struct nvgpu_pbdma_status_info { u32 pbdma_channel_status; /** Channel or tsg id of the context currently loaded on the pbdma. */ u32 id; - /** Specifies whether id is of channel or tsg type. */ + /** Specifies whether #id is of channel or tsg type. */ u32 id_type; /** Channel or tsg id of the next context to be loaded on the pbdma. */ u32 next_id; - /** Specifies whether next id is of channel or tsg type. */ + /** Specifies whether #next_id is of channel or tsg type. */ u32 next_id_type; /** Enum for chan_status field of pbdma_status h/w register. */ enum nvgpu_pbdma_status_chsw_status chsw_status; diff --git a/drivers/gpu/nvgpu/include/nvgpu/runlist.h b/drivers/gpu/nvgpu/include/nvgpu/runlist.h index 1043ed112..71131e3ad 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/runlist.h +++ b/drivers/gpu/nvgpu/include/nvgpu/runlist.h @@ -263,11 +263,10 @@ void nvgpu_runlist_set_state(struct gk20a *g, u32 runlists_mask, u32 runlist_state); /** - * @brief Initialize runlist context + * @brief Initialize runlist context for current GPU * * @param g [in] The GPU driver struct owning the runlists. * - * Initializes runlist context for current GPU: * - Determine number of runlists and max entries per runlists. * - Determine active runlists, i.e. runlists that are mapped to one engine. * - For each active runlist, diff --git a/drivers/gpu/nvgpu/include/nvgpu/tsg.h b/drivers/gpu/nvgpu/include/nvgpu/tsg.h index 7938ab8f6..f2bc53824 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/tsg.h +++ b/drivers/gpu/nvgpu/include/nvgpu/tsg.h @@ -89,8 +89,10 @@ struct nvgpu_tsg { */ struct nvgpu_mem *eng_method_buffers; - - /** Allocated during TSG open and freed during TSG release */ + /** + * Pointer to graphics context buffer for this TSG. Allocated during + * TSG open and freed during TSG release. + */ struct nvgpu_gr_ctx *gr_ctx; /** * This ref is initialized during tsg setup s/w. @@ -99,7 +101,7 @@ struct nvgpu_tsg { */ struct nvgpu_ref refcount; - /** List of channels bound to a tsgid */ + /** List of channels bound to this TSG. */ struct nvgpu_list_node ch_list; #ifdef CONFIG_NVGPU_CHANNEL_TSG_CONTROL /** @@ -141,11 +143,12 @@ struct nvgpu_tsg { unsigned int timeslice_us; /** - * See include/nvgpu/runlist.h and - * refer #NVGPU_FIFO_RUNLIST_INTERLEAVE_LEVEL_LOW. + * Interleave level decides the number of entries of this TSG in the + * runlist. + * Refer #NVGPU_FIFO_RUNLIST_INTERLEAVE_LEVEL_LOW. */ u32 interleave_level; - /** This ranges from 0 to #nvgpu_fifo.num_channels. */ + /** TSG identifier, ranges from 0 to #nvgpu_fifo.num_channels. */ u32 tsgid; /** @@ -154,6 +157,11 @@ struct nvgpu_tsg { struct nvgpu_runlist *runlist; /** tgid (OS specific) of the process that openend the TSG. */ + + /** + * Thread Group identifier (OS specific) of the process that openend + * the TSG. + */ pid_t tgid; /** * Number of active TPCs as requested by userspace. @@ -171,10 +179,13 @@ struct nvgpu_tsg { /** * Set to true if tsgid is acquired else set to false. * This is protected by #nvgpu_fifo.tsg_inuse_mutex. Acquire/Release - * to check if tsgid is already acquired or not. + * the mutex to check if tsgid is already acquired or not. */ bool in_use; - /** Non abortable TSG is for vidmem clear */ + /** + * This will indicate if TSG can be aborted. Non abortable TSG is for + * vidmem clear. + */ bool abortable; /** MMU debug mode enabled if mmu_debug_mode_refcnt > 0 */ @@ -257,14 +268,13 @@ void nvgpu_tsg_release(struct nvgpu_ref *ref); * * @param g [in] The GPU driver struct. * - * Initialize s/w context for TSGs: * - Allocate zero initialized kernel memory area for #nvgpu_fifo.num_channels * number of #nvgpu_fifo.tsg struct. This area of memory is indexed by * tsgid starting from 0 to #nvgpu_fifo.num_channels. * - Upon successful allocation of memory, initialize memory area assigned to * each TSG with s/w defaults. * - * @return 0 for successful init. + * @return 0 for successful init, < 0 for failure. * @retval -ENOMEM if kernel memory could not be allocated to support TSG * s/w context. */ @@ -275,7 +285,6 @@ int nvgpu_tsg_setup_sw(struct gk20a *g); * * @param g [in] The GPU driver struct. * - * De-initialize s/w context for TSGs: * - Destroy s/w context for all tsgid starting from 0 to * #nvgpu_fifo.num_channels. * - De-allocate kernel memory area allocated to support s/w context of @@ -292,9 +301,9 @@ void nvgpu_tsg_cleanup_sw(struct gk20a *g); * #NVGPU_INVALID_TSG_ID, get pointer to area of memory, reserved for s/w * context of TSG and indexed by tsgid. * + * @note This does not check if tsgid is < num_channels. * @return Pointer to #nvgpu_tsg struct. * @retval NULL if tsgid of the given channel is #NVGPU_INVALID_TSG_ID. - * @note This does not check if tsgid is < num_channels. */ struct nvgpu_tsg *nvgpu_tsg_from_ch(struct nvgpu_channel *ch); @@ -328,7 +337,7 @@ void nvgpu_tsg_disable(struct nvgpu_tsg *tsg); * - Get #nvgpu_tsg.refcount to prevent TSG from being freed till channel/s are * bound to this TSG. * - * @return 0 for successful bind + * @return 0 for successful bind, < 0 for failure. * @retval -EINVAL if channel is already bound to a TSG. * @retval -EINVAL if channel is already active. This is done by checking if * bit corresponding to chid is set in the @@ -519,7 +528,7 @@ int nvgpu_tsg_set_interleave(struct nvgpu_tsg *tsg, u32 level); * * @param g [in] The GPU driver struct. * - * Get TSG timeslice value in microseconds. This is the default timeslice + * This function returns TSG timeslice value. This is the default timeslice * value in us as defined by s/w. * * @return S/w defined default TSG timeslice value in us. @@ -533,8 +542,8 @@ u32 nvgpu_tsg_default_timeslice_us(struct gk20a *g); * @param tsg [in] Pointer to the TSG struct. * @param num_sm [in] Total number of SMs supported by h/w. * - * Allocate zero initialized memory to store SM errors for all the SMs - * supported by h/w. + * Allocate zero initialized memory to #nvgpu_tsg_sm_error_state, which stores + * SM errors for all the SMs supported by h/w. * * @return 0 in case of success, < 0 in case of failure. * @retval -EINVAL if memory is already allocated to store @@ -623,7 +632,7 @@ gk20a_event_id_data_from_event_id_node(struct nvgpu_list_node *node) * @param tsg [in] Pointer to TSG struct. * @param error_notifier [in] Error notifier defined by s/w. * - * Set error notifier for all the channels bound to the tsg. + * For each channel bound to given TSG, set given error notifier. * See include/nvgpu/error_notifier.h. */ void nvgpu_tsg_set_error_notifier(struct gk20a *g, struct nvgpu_tsg *tsg,