gpu: nvgpu: ltc: doxygen for common.ltc hals

Moved ltc hals from gk20a.h to newly created file gops_ltc.h.
Added doxygen documentation for ltc hal functions.

JIRA NVGPU-2417

Change-Id: I2b793d7cc27bd54722f37f09af8aea70b5f0dff9
Signed-off-by: Seshendra Gadagottu <sgadagottu@nvidia.com>
Reviewed-on: https://git-master.nvidia.com/r/2220582
GVS: Gerrit_Virtual_Submit
Reviewed-by: Vinod Gopalakrishnakurup <vinodg@nvidia.com>
Reviewed-by: mobile promotions <svcmobile_promotions@nvidia.com>
Tested-by: mobile promotions <svcmobile_promotions@nvidia.com>

arch/nvgpu-common.yaml

@@ -92,6 +92,7 @@ ltc:
   safe: yes
   owner: Seshendra G
   sources: [ common/ltc/ltc.c,
+             include/nvgpu/gops_ltc.h,
              include/nvgpu/ltc.h ]
 
 cbc:

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

@@ -46,6 +46,7 @@
  *   - @ref unit-cg
  *   - @ref unit-pmu
  *   - @ref unit-common-nvgpu
+ *   - @ref unit-common-ltc
  *   - Etc, etc.
  *
  * NVGPU Software Unit Design Documentation
@@ -136,6 +137,7 @@ enum nvgpu_unit;
 #include <nvgpu/gops_gr.h>
 #include <nvgpu/gops_fifo.h>
 #include <nvgpu/gops_fuse.h>
+#include <nvgpu/gops_ltc.h>
 #include <nvgpu/gops_ramfc.h>
 #include <nvgpu/gops_ramin.h>
 #include <nvgpu/gops_runlist.h>
@@ -251,44 +253,8 @@ struct gpu_ops {
 		int (*acr_init)(struct gk20a *g);
 		int (*acr_construct_execute)(struct gk20a *g);
 	} acr;
-	struct {
-		int (*init_ltc_support)(struct gk20a *g);
-		void (*ltc_remove_support)(struct gk20a *g);
-		u64 (*determine_L2_size_bytes)(struct gk20a *gk20a);
-		struct nvgpu_hw_err_inject_info_desc * (*get_ltc_err_desc)
-			(struct gk20a *g);
-		void (*set_enabled)(struct gk20a *g, bool enabled);
-		void (*init_fs_state)(struct gk20a *g);
-		void (*flush)(struct gk20a *g);
-#ifdef CONFIG_NVGPU_GRAPHICS
-		void (*set_zbc_color_entry)(struct gk20a *g,
-					    u32 *color_val_l2,
-					    u32 index);
-		void (*set_zbc_depth_entry)(struct gk20a *g,
-					    u32 depth_val,
-					    u32 index);
-		void (*set_zbc_s_entry)(struct gk20a *g,
-					    u32 s_val,
-					    u32 index);
-#endif
-#ifdef CONFIG_NVGPU_DEBUGGER
-		bool (*pri_is_ltc_addr)(struct gk20a *g, u32 addr);
-		bool (*is_ltcs_ltss_addr)(struct gk20a *g, u32 addr);
-		bool (*is_ltcn_ltss_addr)(struct gk20a *g, u32 addr);
-		void (*split_lts_broadcast_addr)(struct gk20a *g, u32 addr,
-							u32 *priv_addr_table,
-							u32 *priv_addr_table_index);
-		void (*split_ltc_broadcast_addr)(struct gk20a *g, u32 addr,
-							u32 *priv_addr_table,
-							u32 *priv_addr_table_index);
-#endif
-		struct {
-			void (*configure)(struct gk20a *g);
-			void (*isr)(struct gk20a *g, u32 ltc);
-			void (*en_illegal_compstat)(struct gk20a *g,
-								bool enable);
-		} intr;
-	} ltc;
+
+	struct gops_ltc ltc;
 #ifdef CONFIG_NVGPU_COMPRESSION
 	struct {
 		int (*cbc_init_support)(struct gk20a *g);

drivers/gpu/nvgpu/include/nvgpu/gops_ltc.h

@@ -0,0 +1,148 @@
+/*
+ * 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_LTC_H
+#define NVGPU_GOPS_LTC_H
+
+#include <nvgpu/types.h>
+
+/**
+ * @file
+ *
+ * common.ltc interface.
+ */
+struct gk20a;
+
+/**
+ * common.ltc intr subunit hal operations.
+ *
+ * This structure stores common.ltc interrupt subunit hal pointers.
+ *
+ * @see gpu_ops
+ */
+struct gops_ltc_intr {
+	/**
+	 * @brief ISR for handling ltc interrupts.
+	 *
+	 * @param g [in]		Pointer to GPU driver struct.
+	 * @param ltc [in]		LTC unit number
+	 *
+	 * This function handles ltc related ecc interrupts.
+	 */
+	void (*isr)(struct gk20a *g, u32 ltc);
+
+	/** @cond DOXYGEN_SHOULD_SKIP_THIS */
+	void (*configure)(struct gk20a *g);
+	void (*en_illegal_compstat)(struct gk20a *g, bool enable);
+	/** @endcond DOXYGEN_SHOULD_SKIP_THIS */
+};
+
+/**
+ * common.ltc unit hal operations.
+ *
+ * This structure stores common.ltc unit hal pointers.
+ *
+ * @see gpu_ops
+ */
+struct gops_ltc {
+	/**
+	 * @brief Initialize LTC support.
+	 *
+	 * @param g [in]		Pointer to GPU driver struct.
+	 *
+	 * This function reads ltc unit info from GPU h/w and stores
+	 * it in #nvgpu_ltc structure.
+	 *
+	 * @return 0 in case of success, < 0 in case of failure.
+	 * @retval -ENOMEM if memory allocation fails for #nvgpu_ltc.
+	 */
+	int (*init_ltc_support)(struct gk20a *g);
+
+	/**
+	 * @brief Remove LTC support.
+	 *
+	 * @param g [in]		Pointer to GPU driver struct.
+	 *
+	 * This function will free memory allocated for #nvgpu_ltc structure.
+	 */
+	void (*ltc_remove_support)(struct gk20a *g);
+
+	/**
+	 * @brief Returns GPU L2 cache size.
+	 *
+	 * @param g [in]		Pointer to GPU driver struct.
+	 *
+	 * This function returns GPU L2 cache size by reading h/w ltc
+	 * config register.
+	 *
+	 * @return Size of L2 cache in bytes.
+	 */
+	u64 (*determine_L2_size_bytes)(struct gk20a *g);
+
+	/**
+	 * @brief Flush GPU L2 cache.
+	 *
+	 * @param g [in]		Pointer to GPU driver struct.
+	 *
+	 * This function flushes all L2 cache data to main memory by cleaning
+	 * and invaliding all cache sub-units. s/w will poll for completion of
+	 * each ltc unit cache cleaning/invalidation for 5 msec. This 5 msec
+	 * time out is based on following calculations:
+	 * Lowest EMC clock rate will be around 102MHz and thus available
+	 * bandwidth is 64b * 2 * 102MHz = 1.3GB/s. Of that bandwidth, GPU
+	 * will likely get about half, so 650MB/s at worst. Assuming at most
+	 * 1MB of GPU L2 cache, worst case it will take 1MB/650MB/s = 1.5ms.
+	 * So 5ms timeout here should be more than enough.
+	 */
+	void (*flush)(struct gk20a *g);
+
+	/** This structure stores ltc interrupt subunit hal pointers. */
+	struct gops_ltc_intr intr;
+
+	/** @cond DOXYGEN_SHOULD_SKIP_THIS */
+	void (*init_fs_state)(struct gk20a *g);
+	void (*set_enabled)(struct gk20a *g, bool enabled);
+	struct nvgpu_hw_err_inject_info_desc * (*get_ltc_err_desc)
+							(struct gk20a *g);
+#ifdef CONFIG_NVGPU_GRAPHICS
+	void (*set_zbc_color_entry)(struct gk20a *g,
+					u32 *color_val_l2, u32 index);
+	void (*set_zbc_depth_entry)(struct gk20a *g,
+					u32 depth_val, u32 index);
+	void (*set_zbc_s_entry)(struct gk20a *g,
+					u32 s_val, u32 index);
+#endif
+#ifdef CONFIG_NVGPU_DEBUGGER
+	bool (*pri_is_ltc_addr)(struct gk20a *g, u32 addr);
+	bool (*is_ltcs_ltss_addr)(struct gk20a *g, u32 addr);
+	bool (*is_ltcn_ltss_addr)(struct gk20a *g, u32 addr);
+	void (*split_lts_broadcast_addr)(struct gk20a *g, u32 addr,
+						u32 *priv_addr_table,
+						u32 *priv_addr_table_index);
+	void (*split_ltc_broadcast_addr)(struct gk20a *g, u32 addr,
+						u32 *priv_addr_table,
+						u32 *priv_addr_table_index);
+#endif
+	/** @endcond DOXYGEN_SHOULD_SKIP_THIS */
+
+};
+
+#endif /* NVGPU_GOPS_LTC_H */