gpu: nvgpu: move ce gpu_ops out of gk20a.h and add doxygen comments

gk20a.h will include gops_ce.h to contain ce ops definitions. Add
doxygen comments for HAL functions that are called directly.

JIRA NVGPU-4143

Change-Id: I74a29c00b717808351327980292c9b1baefa553d
Signed-off-by: Sagar Kamble <skamble@nvidia.com>
Reviewed-on: https://git-master.nvidia.com/r/2221662
GVS: Gerrit_Virtual_Submit
Reviewed-by: Philip Elcan <pelcan@nvidia.com>
Reviewed-by: Alex Waterman <alexw@nvidia.com>
Reviewed-by: mobile promotions <svcmobile_promotions@nvidia.com>
Tested-by: mobile promotions <svcmobile_promotions@nvidia.com>

arch/nvgpu-common.yaml

@@ -33,7 +33,8 @@ ce:
   safe: yes
   owner: Thomas F
   sources: [ common/ce/ce.c,
-             include/nvgpu/ce.h ]
+             include/nvgpu/ce.h,
+             include/nvgpu/gops_ce.h ]
   deps:
 
 ce_app:

drivers/gpu/nvgpu/include/nvgpu/ce.h

@@ -50,7 +50,15 @@
  *
  * Dynamic Design
  * ==============
- * NA
+ *
+ * At runtime, the CE stalling and non-stalling interrupts are handled through
+ * CE unit hal interfaces. TSG initialization calls CE unit hal interface to
+ * get the number of physical CEs.
+ *
+ * External APIs
+ * -------------
+ * Dynamic interfaces are HAL functions. They are documented here:
+ *   + include/nvgpu/gops_ce.h
  */
 
 struct gk20a;

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

@@ -136,6 +136,7 @@ enum nvgpu_unit;
 #include <nvgpu/semaphore.h>
 #include <nvgpu/fifo.h>
 
+#include <nvgpu/gops_ce.h>
 #include <nvgpu/gops_ptimer.h>
 #include <nvgpu/gops_top.h>
 #include <nvgpu/gops_gr.h>
@@ -274,18 +275,7 @@ struct gpu_ops {
 		u32 (*fix_config)(struct gk20a *g, int base);
 	} cbc;
 #endif
-	struct {
-		int (*ce_init_support)(struct gk20a *g);
-		int (*ce_app_init_support)(struct gk20a *g);
-		void (*ce_app_suspend)(struct gk20a *g);
-		void (*ce_app_destroy)(struct gk20a *g);
-		void (*set_pce2lce_mapping)(struct gk20a *g);
-		void (*isr_stall)(struct gk20a *g, u32 inst_id, u32 pri_base);
-		u32 (*isr_nonstall)(struct gk20a *g, u32 inst_id, u32 pri_base);
-		u32 (*get_num_pce)(struct gk20a *g);
-		void (*mthd_buffer_fault_in_bar2_fault)(struct gk20a *g);
-		void (*init_prod_values)(struct gk20a *g);
-	} ce;
+	struct gops_ce ce;
 	struct gops_gr gr;
 	struct {
 		bool (*is_valid)(u32 class_num);

drivers/gpu/nvgpu/include/nvgpu/gops_ce.h

@@ -0,0 +1,131 @@
+/*
+ * Copyright (c) 2019, 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"),
+ * to deal in the Software without restriction, including without limitation
+ * the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ * and/or sell copies of the Software, and to permit persons to whom the
+ * Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+ * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ * DEALINGS IN THE SOFTWARE.
+ */
+#ifndef NVGPU_GOPS_CE_H
+#define NVGPU_GOPS_CE_H
+
+#include <nvgpu/types.h>
+
+/**
+ * @file
+ *
+ * CE HAL interface.
+ */
+struct gk20a;
+
+/**
+ * CE HAL operations.
+ *
+ * @see gpu_ops.
+ */
+struct gops_ce {
+	/**
+	 * @brief Handler for CE stalling interrupts.
+	 *
+	 * @param g [in]	The GPU driver struct.
+	 * @param inst_id [in]	Copy engine instance id.
+	 * @param pri_base [in]	Start of h/w register address space.
+	 *
+	 * This function is invoked by MC stalling isr handler to handle
+	 * the CE stalling interrupt.
+	 *
+	 * Steps:
+	 * - Read ce_intr_status_r corresponding to \a inst_id.
+	 * - Check if following error interrupts are pending. If pending,
+	 *   report that error to the SDL framework and mark the interrupt
+	 *   for clearing.
+	 *   - Invalid config interrupt.
+	 *   - Method buffer fault interrupt.
+	 *   - Blocking pipe interrupt.
+	 *   - Launch error interrupt.
+	 * - Clear the handled interrupts by write to ce_intr_status_r.
+	 */
+	void (*isr_stall)(struct gk20a *g, u32 inst_id, u32 pri_base);
+
+	/**
+	 * @brief Handler for CE non-stalling interrupts.
+	 *
+	 * @param g [in]	The GPU driver struct.
+	 * @param inst_id [in]	Copy engine instance id.
+	 * @param pri_base [in]	Start of h/w register address space.
+	 *
+	 * This function is invoked by MC non-stalling isr handler to handle
+	 * the CE non-stalling interrupt.
+	 *
+	 * Steps:
+	 * - Read ce_intr_status_r corresponding to \a inst_id.
+	 * - If nonblocking pipe interrupt is pending,
+	 *   - Report the error to the SDL framework.
+	 *   - Clear the interrupt.
+	 *   - Return bitmask #NVGPU_NONSTALL_OPS_WAKEUP_SEMAPHORE |
+	 *     #NVGPU_NONSTALL_OPS_POST_EVENTS.
+	 *
+	 * @return Bitmask of operations that will need to be executed on
+	 *         non stall workqueue.
+	 */
+	u32 (*isr_nonstall)(struct gk20a *g, u32 inst_id, u32 pri_base);
+
+	/**
+	 * @brief Get number of PCEs (Physical Copy Engines).
+	 *
+	 * @param g [in]	The GPU driver struct.
+	 *
+	 * This function is called to determine the size of the engine method
+	 * buffer during tsg initialization.
+	 *
+	 * Steps:
+	 * - Read ce_pce_map_r register that contains a bitmask indicating which
+	 *   physical copy engines are present (and not floorswept).
+	 * - Compute and return the Hamming weight of the read value.
+	 *
+	 * @return Number of PCEs.
+	 */
+	u32 (*get_num_pce)(struct gk20a *g);
+
+	/**
+	 * @brief Handler for method buffer fault in BAR2.
+	 *
+	 * @param g [in]	The GPU driver struct.
+	 *
+	 * This function is called while handling bar2 fault in the fb
+	 * interrupt handler.
+	 *
+	 * Steps:
+	 * - For each LCE, check if method buffer fault interrupt is pending and
+	 *   clear if pending.
+	 */
+	void (*mthd_buffer_fault_in_bar2_fault)(struct gk20a *g);
+
+	/** @cond DOXYGEN_SHOULD_SKIP_THIS */
+
+	int (*ce_init_support)(struct gk20a *g);
+	void (*set_pce2lce_mapping)(struct gk20a *g);
+	void (*init_prod_values)(struct gk20a *g);
+
+#ifdef CONFIG_NVGPU_DGPU
+	int (*ce_app_init_support)(struct gk20a *g);
+	void (*ce_app_suspend)(struct gk20a *g);
+	void (*ce_app_destroy)(struct gk20a *g);
+#endif
+	/** @endcond DOXYGEN_SHOULD_SKIP_THIS */
+};
+
+#endif/*NVGPU_GOPS_CE_H*/