From ce8358ef2b0b4d3fa38a6345a56d2891677bf17c Mon Sep 17 00:00:00 2001
From: Deepak Nibade <dnibade@nvidia.com>
Date: Mon, 14 Dec 2020 20:10:39 +0530
Subject: [PATCH] gpu: nvgpu: update common.gr doxygen to match swud

Update doxygen comments for common.gr functions used in initialization,
context creation, and interrupt handling usecases to closely match
design description in SWUD.

Add details on why those APIs are needed.

Jira NVGPU-6180

Change-Id: I6f987a797eb9412a0a8853b37c9f13f18d9717c2
Signed-off-by: Deepak Nibade <dnibade@nvidia.com>
Reviewed-on: https://git-master.nvidia.com/r/c/linux-nvgpu/+/2459526
(cherry picked from commit 0dffeb056656b403ef3bc2ef2c54732da5de2bd9)
Reviewed-on: https://git-master.nvidia.com/r/c/linux-nvgpu/+/2461159
GVS: Gerrit_Virtual_Submit
Tested-by: mobile promotions <svcmobile_promotions@nvidia.com>
Reviewed-by: Rajesh Devaraj <rdevaraj@nvidia.com>
Reviewed-by: mobile promotions <svcmobile_promotions@nvidia.com>
---
 drivers/gpu/nvgpu/include/nvgpu/gr/gr.h      | 11 ++++++++---
 drivers/gpu/nvgpu/include/nvgpu/gr/gr_intr.h |  3 ++-
 drivers/gpu/nvgpu/include/nvgpu/gr/setup.h   |  5 ++++-
 3 files changed, 14 insertions(+), 5 deletions(-)

diff --git a/drivers/gpu/nvgpu/include/nvgpu/gr/gr.h b/drivers/gpu/nvgpu/include/nvgpu/gr/gr.h
index 8861b3a9c..d2afda908 100644
--- a/drivers/gpu/nvgpu/include/nvgpu/gr/gr.h
+++ b/drivers/gpu/nvgpu/include/nvgpu/gr/gr.h
@@ -120,7 +120,9 @@ struct nvgpu_gr;
 struct nvgpu_gr_config;
 
 /**
- * @brief Allocate memory for GR struct.
+ * @brief Allocate memory for GR struct and initialize the minimum SW
+ *        required to enable GR engine HW as phase 1 of GR engine
+ *        initialization.
  *
  * @param g [in]	Pointer to GPU driver struct.
  *
@@ -154,7 +156,8 @@ int nvgpu_gr_alloc(struct gk20a *g);
 void nvgpu_gr_free(struct gk20a *g);
 
 /**
- * @brief Enable GR engine h/w.
+ * @brief Reset and enable GR engine HW as phase 2 of GR engine
+ *        initialization.
  *
  * @param g [in]	Pointer to GPU driver struct.
  *
@@ -175,7 +178,9 @@ void nvgpu_gr_free(struct gk20a *g);
 int nvgpu_gr_enable_hw(struct gk20a *g);
 
 /**
- * @brief Initialize GR engine support.
+ * @brief Initialize CTXSW, GR engine HW, GR engine interrupts, and
+ *        necessary SW context support as phase 3 (final phase) of GR
+ *        engine initialization.
  *
  * @param g [in]	Pointer to GPU driver struct.
  *
diff --git a/drivers/gpu/nvgpu/include/nvgpu/gr/gr_intr.h b/drivers/gpu/nvgpu/include/nvgpu/gr/gr_intr.h
index b4fccba51..25d57c7c3 100644
--- a/drivers/gpu/nvgpu/include/nvgpu/gr/gr_intr.h
+++ b/drivers/gpu/nvgpu/include/nvgpu/gr/gr_intr.h
@@ -191,7 +191,8 @@ int nvgpu_gr_intr_handle_sm_exception(struct gk20a *g, u32 gpc, u32 tpc, u32 sm,
 		u32 *hww_global_esr);
 
 /**
- * @brief ISR for GR engine stalling interrupts.
+ * @brief ISR to handle any pending GR engine stalling interrupts reported
+ *        by HW and to report them to qnx.sdl unit.
  *
  * @param g [in]		Pointer to GPU driver struct.
  *
diff --git a/drivers/gpu/nvgpu/include/nvgpu/gr/setup.h b/drivers/gpu/nvgpu/include/nvgpu/gr/setup.h
index aa6284c56..c030b411d 100644
--- a/drivers/gpu/nvgpu/include/nvgpu/gr/setup.h
+++ b/drivers/gpu/nvgpu/include/nvgpu/gr/setup.h
@@ -45,6 +45,8 @@ struct nvgpu_gr_ctx;
 
 /**
  * @brief Allocate and setup object context s/w image for GPU channel.
+ *        Application requires that a channel context is created and
+ *        initialized before any work is submitted to GR HW.
  *
  * @param c [in]		Pointer to GPU channel.
  * @param class_num [in]	GPU class ID.
@@ -106,7 +108,8 @@ void nvgpu_gr_setup_free_gr_ctx(struct gk20a *g,
 void nvgpu_gr_setup_free_subctx(struct nvgpu_channel *c);
 
 /**
- * @brief Setup preemption mode in GR engine context image.
+ * @brief Setup preemption mode in GR engine context image in case
+ *        Application optionally wants to change default preemption mode.
  *
  * @param ch [in]			Pointer to GPU channel.
  * @param graphics_preempt_mode [in]	Requested graphics preemption mode.