gpu: nvgpu: doxygen for gr/gr.h

Add doxygen documentation for gr/gr.h header.
Also add necessary plumbing to add common.gr unit documentation HTML
link.

Fix gr_init_reset_enable_hw() to return error code in case of error.

Compile nvgpu_gr_enable_ctxsw()/nvgpu_gr_disable_ctxsw() only if
debugger or recovery support is enabled.

Jira NVGPU-3911

Change-Id: Iaa942748a00aeffce9349cb0669d2cd5baca1e55
Signed-off-by: Deepak Nibade <dnibade@nvidia.com>
Reviewed-on: https://git-master.nvidia.com/r/2180312
Reviewed-by: mobile promotions <svcmobile_promotions@nvidia.com>
Tested-by: mobile promotions <svcmobile_promotions@nvidia.com>

drivers/gpu/nvgpu/common/gr/gr.c

@@ -520,7 +520,7 @@ out:
 		nvgpu_log_fn(g, "done");
 	}
 
-	return 0;
+	return err;
 }
 
 int nvgpu_gr_prepare_sw(struct gk20a *g)
@@ -720,6 +720,7 @@ void nvgpu_gr_free(struct gk20a *g)
 	g->gr = NULL;
 }
 
+#if defined(CONFIG_NVGPU_RECOVERY) || defined(CONFIG_NVGPU_DEBUGGER)
 /**
  * Stop processing (stall) context switches at FECS:-
  * If fecs is sent stop_ctxsw method, elpg entry/exit cannot happen
@@ -809,6 +810,7 @@ ctxsw_already_enabled:
 
 	return err;
 }
+#endif
 
 void nvgpu_gr_remove_support(struct gk20a *g)
 {

drivers/gpu/nvgpu/include/nvgpu/gk20a.h

@@ -35,6 +35,7 @@
  *
  *   - @ref unit-mm
  *   - @ref unit-fifo
+ *   - @ref unit-gr
  *   - @ref unit-devctl
  *   - @ref unit-sdl
  *   - @ref unit-init

drivers/gpu/nvgpu/include/nvgpu/gr/gr.h

@@ -25,27 +25,279 @@
 
 #include <nvgpu/types.h>
 
+/**
+ * @file
+ * @page unit-gr Unit GR
+ *
+ * Overview
+ * ========
+ *
+ * common.gr unit is responsible for managing the GR engine on the GPU.
+ * There are two aspects of GR engine support managed by this unit:
+ *
+ * - GR engine h/w.
+ * - GR engine s/w context images.
+ *
+ * GR engine h/w management
+ * ------------------------
+ *
+ * common.gr unit has below responsibilities to manage GR engine h/w:
+ *
+ * - Enable GR engine h/w.
+ * - Allocate all necessary s/w data structures to hold GR engine
+ *   configuration.
+ * - Configure GR engine h/w to a known good state.
+ * - Populate all s/w data structures while initializing the h/w.
+ *   e.g. populate number of available GPC/TPC/SM components.
+ * - Provide APIs to retrieve GR engine configuration.
+ * - Enable and handle all GR engine interrupts and exceptions.
+ * - Suspend GR engine while preparing GPU for poweroff.
+ * - Remove GR engine s/w support as part of removing GPU support.
+ *
+ * GR engine s/w context image management
+ * --------------------------------------
+ *
+ * common.gr unit has below responsibilities to manage GR engine context
+ * images:
+ *
+ * - Manage all global context images.
+ * - Manage GR engine context (per GPU Time Slice Group).
+ * - Manage subcontext (per GPU channel).
+ * - Allocate Golden context image.
+ * - Map/unmap all global context images into GR engine context.
+ *
+ * Data Structures
+ * ===============
+ *
+ * common.gr unit does not expose any public data structure.
+ *
+ * Static Design
+ * =============
+ *
+ * Resource utilization
+ * --------------------
+ *
+ * External APIs
+ * -------------
+ *
+ * Supporting Functionality
+ * ========================
+ *
+ * Dependencies
+ * ------------
+ *
+ * Dynamic Design
+ * ==============
+ *
+ * Open Items
+ * ==========
+ *
+ */
 struct gk20a;
 struct nvgpu_gr_config;
 
-u32 nvgpu_gr_get_no_of_sm(struct gk20a *g);
+/**
+ * @brief Allocate memory for GR struct.
+ *
+ * @param g[in]		Pointer to GPU driver struct.
+ *
+ * This function allocates memory for GR struct (i.e. struct nvgpu_gr).
+ *
+ * @return 0 in case of success, < 0 in case of failure.
+ * @retval -ENOMEM if memory allocation fails for GR struct.
+ */
+int nvgpu_gr_alloc(struct gk20a *g);
+
+/**
+ * @brief Free GR struct.
+ *
+ * @param g[in]		Pointer to GPU driver struct.
+ *
+ * This function ensures that memory allocated for GR struct is released
+ * during deinitialization.
+ */
+void nvgpu_gr_free(struct gk20a *g);
+
+/**
+ * @brief Initialize GR struct fields
+ *
+ * @param g[in]		Pointer to GPU driver struct.
+ *
+ * Calling this function ensures that various GR struct fields are
+ * initialized before they are referenced by other units or before
+ * GR initialization sequence is executed.
+ */
+void nvgpu_gr_init(struct gk20a *g);
+
+/**
+ * @brief Initialize the s/w required to enable h/w.
+ *
+ * @param g[in]		Pointer to GPU driver struct.
+ *
+ * This function executes only a subset of s/w initialization sequence
+ * that is required to enable GR engine h/w in #nvgpu_gr_enable_hw().
+ *
+ * This initialization includes reading netlist ucode and allocating
+ * memory for internal data structures required to enable h/w.
+ *
+ * Note that all rest of the s/w initialization is completed in
+ * #nvgpu_gr_init_support() function.
+ *
+ * @return 0 in case of success, < 0 in case of failure.
+ * @retval -ENOMEM if memory allocation fails for any internal data
+ *         structure.
+ */
 int nvgpu_gr_prepare_sw(struct gk20a *g);
+
+/**
+ * @brief Enable GR engine h/w.
+ *
+ * @param g[in]		Pointer to GPU driver struct.
+ *
+ * This function enables GR engine h/w. This includes resetting GR
+ * engine in MC, loading PROD register values, enabling GR engine
+ * interrupts, ensuring falcon memory is scrubbed, etc.
+ *
+ * @return 0 in case of success, < 0 in case of failure.
+ * @retval -ETIMEDOUT if falcon mem scrubbing times out.
+ * @retval -EAGAIN if GR engine idle wait times out.
+ */
 int nvgpu_gr_enable_hw(struct gk20a *g);
+
+/**
+ * @brief Initialize GR engine support.
+ *
+ * @param g[in]		Pointer to GPU driver struct.
+ *
+ * This function initializes all the GR engine support and
+ * functionality. This includes:
+ * - Initializing context switch ucode.
+ * - Reading Golden context image size from FECS micro controller.
+ * - Allocating memory for all internal data structures.
+ * - Allocating global context buffers.
+ * - Initializing GR engine h/w registers to known good values.
+ * - Reading GR engine configuration (like number of GPC/TPC/SM etc)
+ *   after considering floorsweeping.
+ *
+ * This function must be called in this sequence:
+ * - nvgpu_gr_prepare_sw()
+ * - nvgpu_gr_enable_hw()
+ * - nvgpu_gr_init_support()
+ *
+ * @return 0 in case of success, < 0 in case of failure.
+ * @retval -ENOENT if context switch ucode is not found.
+ * @retval -ETIMEDOUT if context switch ucode times out.
+ * @retval -ETIMEDOUT if reading golden context size times out.
+ * @retval -ENOMEM if memory allocation fails for any internal data
+ *         structure.
+ */
+int nvgpu_gr_init_support(struct gk20a *g);
+
+/**
+ * @brief Wait for GR engine to be initialized
+ *
+ * @param g[in]		Pointer to GPU driver struct.
+ *
+ * Calling this function ensures that GR engine initialization i.e.
+ * nvgpu_gr_init_support() function call is complete.
+ */
+void nvgpu_gr_wait_initialized(struct gk20a *g);
+
+/**
+ * @brief Set GR s/w ready status.
+ *
+ * @param g[in]		Pointer to GPU driver struct.
+ * @param enable[in]	Boolean flag.
+ *
+ * This function sets/unsets GR s/w ready status in struct nvgpu_gr.
+ * Setting of flag is typically needed during initialization of GR s/w.
+ * Unsetting of flag is needed while preparing for poweroff.
+ */
+void nvgpu_gr_sw_ready(struct gk20a *g, bool enable);
+
+/**
+ * @brief Get number of SMs in GR engine.
+ *
+ * @param g[in]		Pointer to GPU driver struct.
+ *
+ * This function returns number of SMs available in GR engine.
+ * Note that this count is initialized only after GR engine is
+ * completely initialized through #nvgpu_gr_init_support().
+ *
+ * @return number of available SMs in GR engine.
+ */
+u32 nvgpu_gr_get_no_of_sm(struct gk20a *g);
+
+/**
+ * @brief Suspend GR engine.
+ *
+ * @param g[in]		Pointer to GPU driver struct.
+ *
+ * This function is typically called while preparing for GPU power off.
+ * This function makes sure that GR engine is idle before power off.
+ * It will also disable all GR engine interrupts and exceptions.
+ *
+ * @return 0 in case of success, < 0 in case of failure.
+ * @retval -EAGAIN if GR engine idle wait times out.
+ */
+int nvgpu_gr_suspend(struct gk20a *g);
+
+/**
+ * @brief Remove GR engine s/w support.
+ *
+ * @param g[in]		Pointer to GPU driver struct.
+ *
+ * This is typically called while removing entire GPU driver.
+ * This function will ensure that all memory and other system resources
+ * allocated during GR s/w initialization are released appropriately.
+ */
+void nvgpu_gr_remove_support(struct gk20a *g);
+
+/**
+ * @brief Get base register offset of a given GPC.
+ *
+ * @param g[in]		Pointer to GPU driver struct.
+ * @param gpc[in]	GPC index.
+ *
+ * This function calculates and returns base register offset of a given
+ * GPC.
+ *
+ * @return base register offset of a given GPC.
+ */
+u32 nvgpu_gr_gpc_offset(struct gk20a *g, u32 gpc);
+
+/**
+ * @brief Get base register offset of a given TPC in a GPC.
+ *
+ * @param g[in]		Pointer to GPU driver struct.
+ * @param tpc[in]	TPC index.
+ *
+ * This function calculates and returns base register offset of a given
+ * TPC within a GPC.
+ *
+ * @return base register offset of a given TPC.
+ */
+u32 nvgpu_gr_tpc_offset(struct gk20a *g, u32 tpc);
+
+/**
+ * @brief Get base register offset of a given SM in a GPC/TPC.
+ *
+ * @param g[in]		Pointer to GPU driver struct.
+ * @param sm[in]	SM index.
+ *
+ * This function calculates and returns base register offset of a given
+ * SM within a GPC/TPC pair.
+ *
+ * @return base register offset of a given SM.
+ */
+u32 nvgpu_gr_sm_offset(struct gk20a *g, u32 sm);
+
+#if defined(CONFIG_NVGPU_RECOVERY) || defined(CONFIG_NVGPU_DEBUGGER)
+int nvgpu_gr_disable_ctxsw(struct gk20a *g);
+int nvgpu_gr_enable_ctxsw(struct gk20a *g);
+#endif
 #ifdef CONFIG_NVGPU_ENGINE_RESET
 int nvgpu_gr_reset(struct gk20a *g);
 #endif
-int nvgpu_gr_init_support(struct gk20a *g);
-u32 nvgpu_gr_gpc_offset(struct gk20a *g, u32 gpc);
-u32 nvgpu_gr_tpc_offset(struct gk20a *g, u32 tpc);
-u32 nvgpu_gr_sm_offset(struct gk20a *g, u32 sm);
-int nvgpu_gr_suspend(struct gk20a *g);
 
-void nvgpu_gr_wait_initialized(struct gk20a *g);
-void nvgpu_gr_init(struct gk20a *g);
-int nvgpu_gr_alloc(struct gk20a *g);
-void nvgpu_gr_free(struct gk20a *g);
-int nvgpu_gr_disable_ctxsw(struct gk20a *g);
-int nvgpu_gr_enable_ctxsw(struct gk20a *g);
-void nvgpu_gr_remove_support(struct gk20a *g);
-void nvgpu_gr_sw_ready(struct gk20a *g, bool enable);
 #endif /* NVGPU_GR_H */