gpu: nvgpu: add full documentation for gk20a header file

-Document all structure fields defined in gk20a.h. -Add few missing documentation for gk20a struct. -Add return value for the public APIs of common.nvgpu unit. Jira NVGPU-6252 Change-Id: I6726d83f6d1a4db5f24c0d94093b2c00263d220a Signed-off-by: shashank singh <shashsingh@nvidia.com> Reviewed-on: https://git-master.nvidia.com/r/c/linux-nvgpu/+/2459287 (cherry picked from commit 9f6f1eddee9ac39918fca345917490e2063bc01e) Reviewed-on: https://git-master.nvidia.com/r/c/linux-nvgpu/+/2466601 Reviewed-by: Deepak Nibade <dnibade@nvidia.com> Reviewed-by: mobile promotions <svcmobile_promotions@nvidia.com> GVS: Gerrit_Virtual_Submit Tested-by: mobile promotions <svcmobile_promotions@nvidia.com>
2025-12-22 17:36:20 +03:00 · 2020-12-14 10:58:07 +05:30
parent f3ee39505c
commit 76f766d6ac
5 changed files with 174 additions and 31 deletions
--- a/drivers/gpu/nvgpu/include/nvgpu/gk20a.h
+++ b/drivers/gpu/nvgpu/include/nvgpu/gk20a.h
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011-2020, NVIDIA CORPORATION.  All rights reserved.
+ * Copyright (c) 2011-2021, NVIDIA CORPORATION.  All rights reserved.
 *
 * GK20A Graphics
 *
@@ -145,6 +145,11 @@ enum nvgpu_profiler_pm_reservation_scope;

 #include "hal/clk/clk_gk20a.h"

+/**
+ * @addtogroup unit-common-nvgpu
+ * @{
+ */
+
 #ifdef CONFIG_DEBUG_FS
 struct railgate_stats {
 	unsigned long last_rail_gate_start;
@@ -157,44 +162,95 @@ struct railgate_stats {
 };
 #endif

+/**
+ * @defgroup NVGPU_COMMON_NVGPU_DEFINES
+ *
+ * GPU litters defines.
+ */
+
+/**
+ * @ingroup NVGPU_COMMON_NVGPU_DEFINES
+ * @{
+ */
+
+/** Number of gpcs. */
 #define GPU_LIT_NUM_GPCS	0
+/** Number of pes per gpc. */
 #define GPU_LIT_NUM_PES_PER_GPC 1
+/** Number of zcull banks. */
 #define GPU_LIT_NUM_ZCULL_BANKS 2
+/** Number of tpcs per gpc. */
 #define GPU_LIT_NUM_TPC_PER_GPC 3
+/** Number of SMs per tpc. */
 #define GPU_LIT_NUM_SM_PER_TPC  4
+/** Number of fbps. */
 #define GPU_LIT_NUM_FBPS	5
+/** Gpc base address. */
 #define GPU_LIT_GPC_BASE	6
+/** Gpc stride. */
 #define GPU_LIT_GPC_STRIDE	7
+/** Gpc shared base offset. */
 #define GPU_LIT_GPC_SHARED_BASE 8
+/** Tpc's base offset in gpc. */
 #define GPU_LIT_TPC_IN_GPC_BASE 9
+/** Tpc's stride in gpc. */
 #define GPU_LIT_TPC_IN_GPC_STRIDE 10
+/** Tpc's shared base offset in gpc. */
 #define GPU_LIT_TPC_IN_GPC_SHARED_BASE 11
+/** Ppc's base offset in gpc. */
 #define GPU_LIT_PPC_IN_GPC_BASE	12
+/** Ppc's stride in gpc. */
 #define GPU_LIT_PPC_IN_GPC_STRIDE 13
+/** Ppc's shared base offset in gpc. */
 #define GPU_LIT_PPC_IN_GPC_SHARED_BASE 14
+/** Rop base offset. */
 #define GPU_LIT_ROP_BASE	15
+/** Rop stride. */
 #define GPU_LIT_ROP_STRIDE	16
+/** Rop shared base offset. */
 #define GPU_LIT_ROP_SHARED_BASE 17
+/** Number of host engines. */
 #define GPU_LIT_HOST_NUM_ENGINES 18
+/** Number of host pbdma. */
 #define GPU_LIT_HOST_NUM_PBDMA	19
+/** LTC stride. */
 #define GPU_LIT_LTC_STRIDE	20
+/** LTS stride. */
 #define GPU_LIT_LTS_STRIDE	21
+/** Number of fbpas. */
 #define GPU_LIT_NUM_FBPAS	22
+/** Fbpa stride. */
 #define GPU_LIT_FBPA_STRIDE	23
+/** Fbpa base offset. */
 #define GPU_LIT_FBPA_BASE	24
+/** Fbpa shared base offset. */
 #define GPU_LIT_FBPA_SHARED_BASE 25
+/** Sm pri stride. */
 #define GPU_LIT_SM_PRI_STRIDE	26
+/** Smpc pri base offset. */
 #define GPU_LIT_SMPC_PRI_BASE		27
+/** Smpc pri shared base offset. */
 #define GPU_LIT_SMPC_PRI_SHARED_BASE	28
+/** Smpc pri unique base offset. */
 #define GPU_LIT_SMPC_PRI_UNIQUE_BASE	29
+/** Smpc pri stride. */
 #define GPU_LIT_SMPC_PRI_STRIDE		30
+/** Twod class. */
 #define GPU_LIT_TWOD_CLASS	31
+/** Threed class. */
 #define GPU_LIT_THREED_CLASS	32
+/** Compute class. */
 #define GPU_LIT_COMPUTE_CLASS	33
+/** Gpfifo class. */
 #define GPU_LIT_GPFIFO_CLASS	34
+/** I2m class. */
 #define GPU_LIT_I2M_CLASS	35
+/** Dma copy class. */
 #define GPU_LIT_DMA_COPY_CLASS	36
+/** Gpc priv stride. */
 #define GPU_LIT_GPC_PRIV_STRIDE	37
+/** Compute class. */
+/** @cond DOXYGEN_SHOULD_SKIP_THIS */
 #define GPU_LIT_PERFMON_PMMGPCTPCA_DOMAIN_START 38
 #define GPU_LIT_PERFMON_PMMGPCTPCB_DOMAIN_START 39
 #define GPU_LIT_PERFMON_PMMGPCTPC_DOMAIN_COUNT  40
@@ -207,9 +263,16 @@ struct railgate_stats {
 #define GPU_LIT_GPC_ADDR_WIDTH			47
 #define GPU_LIT_TPC_ADDR_WIDTH			48
 #define GPU_LIT_MAX_RUNLISTS_SUPPORTED		49
+/** @endcond */

+/** Macro to get litter values corresponding to the litter defines. */
 #define nvgpu_get_litter_value(g, v) ((g)->ops.get_litter_value((g), v))

+/**
+ * @}
+ */
+
+/** @cond DOXYGEN_SHOULD_SKIP_THIS */
 #define MAX_TPC_PG_CONFIGS      9

 struct nvgpu_gpfifo_userdata {
@@ -226,6 +289,7 @@ enum nvgpu_event_id_type {
 	NVGPU_EVENT_ID_GR_SEMAPHORE_WRITE_AWAKEN = 5,
 	NVGPU_EVENT_ID_MAX = 6,
 };
+/** @endcond */

 /**
 * @brief HW version info read from the HW.
@@ -241,6 +305,7 @@ struct nvgpu_gpu_params {
 	u32 sm_arch_sm_version;
 	/** sm instruction set */
 	u32 sm_arch_spa_version;
+	/** total number of physical warps possible on an SM. */
 	u32 sm_arch_warp_count;
 };

@@ -340,8 +405,9 @@ struct gk20a {
 	 */
 	struct nvgpu_rwsem deterministic_busy;
 #endif
-
+	/** Pointer to struct containing netlist data of ucodes. */
 	struct nvgpu_netlist_vars *netlist_vars;
+	/** Flag to indicate initialization status of netlists. */
 	bool netlist_valid;

 	/** Struct holding the pmu falcon software state. */
@@ -620,9 +686,9 @@ struct gk20a {
 	nvgpu_atomic_t clk_arb_global_nr;

 	struct nvgpu_ce_app *ce_app;
-	/** @endcond */

 	bool ltc_intr_en_illegal_compstat;
+	/** @endcond */

 	/** Are we currently running on a FUSA device configuration? */
 	bool is_fusa_sku;
@@ -672,8 +738,11 @@ struct gk20a {
 	/** @endcond */

 #if defined(CONFIG_TEGRA_GK20A_NVHOST)
+	/** Full syncpoint aperture base memory address. */
 	u64		syncpt_unit_base;
+	/** Full syncpoint aperture size. */
 	size_t		syncpt_unit_size;
+	/** Each syncpoint aperture size */
 	u32		syncpt_size;
 #endif
 	/** Full syncpoint aperture. */
@@ -703,7 +772,11 @@ struct gk20a {
 *
 * @param g [in]	The GPU superstucture.
 *
- * @return True if these timeouts are enabled, false otherwise.
+ * @return timeouts enablement status
+ * @retval True  always for safety or if these timeouts are actually enabled on
+ *               other builds.
+ * @retval False never for safety or if these timeouts are actually disabled on
+ *               other builds.
 */
 static inline bool nvgpu_is_timeouts_enabled(struct gk20a *g)
 {
@@ -725,6 +798,8 @@ static inline bool nvgpu_is_timeouts_enabled(struct gk20a *g)
 * @param g [in]	The GPU superstucture.
 *
 * @return The value of the global poll timeout value in us.
+ * @retval NVGPU_DEFAULT_POLL_TIMEOUT_MS for safety as timeout is always
+ *         enabled.
 */
 static inline u32 nvgpu_get_poll_timeout(struct gk20a *g)
 {
--- a/drivers/gpu/nvgpu/include/nvgpu/gops/acr.h
+++ b/drivers/gpu/nvgpu/include/nvgpu/gops/acr.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"),
@@ -22,8 +22,23 @@
 #ifndef NVGPU_GOPS_ACR_H
 #define NVGPU_GOPS_ACR_H

+/**
+ * @brief acr gops.
+ *
+ * The structure contains function pointers to acr init and execute operations.
+ * The details of these callbacks are described in the assigned functions to
+ * these pointers.
+ */
 struct gops_acr {
+	/**
+	 * Initializes ACR unit private data struct in the GPU driver based on
+	 * current chip.
+	 */
 	int (*acr_init)(struct gk20a *g);
+	/**
+	 * Construct blob of LS ucode's in non-wpr memory. Load and bootstrap HS
+	 * ACR ucode on specified engine Falcon.
+	 */
 	int (*acr_construct_execute)(struct gk20a *g);
 };

--- a/drivers/gpu/nvgpu/include/nvgpu/gops/clk.h
+++ b/drivers/gpu/nvgpu/include/nvgpu/gops/clk.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"),
@@ -28,7 +28,15 @@ struct gk20a;
 struct namemap_cfg;
 struct clk_gk20a;

+/**
+ * @brief clk gops.
+ *
+ * The structure contains function pointers to getting clock max rate. The
+ * details of these callbacks are described in the assigned function to these
+ * func pointers.
+ */
 struct gops_clk {
+/** @cond DOXYGEN_SHOULD_SKIP_THIS */
 	int (*init_debugfs)(struct gk20a *g);
 	int (*init_clk_support)(struct gk20a *g);
 	void (*suspend_clk_support)(struct gk20a *g);
@@ -50,7 +58,10 @@ struct gops_clk {
 	u32 (*get_ref_clock_rate)(struct gk20a *g);
 	int (*predict_mv_at_hz_cur_tfloor)(struct clk_gk20a *clk,
 		unsigned long rate);
+/** @endcond */
+	/** Get max rate of gpu clock. */
 	unsigned long (*get_maxrate)(struct gk20a *g, u32 api_domain);
+/** @cond DOXYGEN_SHOULD_SKIP_THIS */
 	int (*prepare_enable)(struct clk_gk20a *clk);
 	void (*disable_unprepare)(struct clk_gk20a *clk);
 	int (*get_voltage)(struct clk_gk20a *clk, u64 *val);
@@ -70,6 +81,7 @@ struct gops_clk {
 	int (*perf_pmu_vfe_load)(struct gk20a *g);
 	bool support_vf_point;
 	u8 lut_num_entries;
+/** @endcond */
 };

 struct gops_clk_mon {
--- a/drivers/gpu/nvgpu/include/nvgpu/gops/fbp.h
+++ b/drivers/gpu/nvgpu/include/nvgpu/gops/fbp.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"),
@@ -22,7 +22,14 @@
 #ifndef NVGPU_GOPS_FBP_H
 #define NVGPU_GOPS_FBP_H

+/**
+ * @brief fbp gops.
+ *
+ * The structure contains function pointers to fbp initialization. The details
+ * of this callback is described in the assigned function to this func pointer.
+ */
 struct gops_fbp {
+	/** Read and initialize FBP configuration information. */
 	int (*fbp_init_support)(struct gk20a *g);
 };

--- a/drivers/gpu/nvgpu/include/nvgpu/gpu_ops.h
+++ b/drivers/gpu/nvgpu/include/nvgpu/gpu_ops.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"),
@@ -76,10 +76,12 @@ struct gk20a;
 struct nvgpu_debug_context;
 struct nvgpu_mem;

+/** @cond DOXYGEN_SHOULD_SKIP_THIS */
 struct gops_debug {
 	void (*show_dump)(struct gk20a *g,
 			struct nvgpu_debug_context *o);
 };
+/** @endcond */

 /**
 * @addtogroup unit-common-nvgpu
@@ -96,52 +98,54 @@ struct gops_debug {
 * struct.
 */
 struct gpu_ops {
-
+	/** Acr hal ops. */
 	struct gops_acr acr;
-	struct gops_sbr sbr;
-	struct gops_func func;
+	/** Ecc hal ops. */
 	struct gops_ecc ecc;
+	/** Ltc hal ops. */
 	struct gops_ltc ltc;
 #ifdef CONFIG_NVGPU_COMPRESSION
 	struct gops_cbc cbc;
 #endif
+	/** Ce hal ops. */
 	struct gops_ce ce;
+	/** Gr hal ops. */
 	struct gops_gr gr;
+	/** Gpu class hal ops. */
 	struct gops_class gpu_class;
+	/** Fb hal ops. */
 	struct gops_fb fb;
-	struct gops_nvdec nvdec;
+	/** Clock gating hal ops. */
 	struct gops_cg cg;
+	/** Fifo hal ops. */
 	struct gops_fifo fifo;
+	/** Fuse hal ops. */
 	struct gops_fuse fuse;
-	struct gops_ramfc ramfc;
-	struct gops_ramin ramin;
+	/** Runlist hal ops. */
 	struct gops_runlist runlist;
-	struct gops_userd userd;
-	struct gops_engine engine;
-	struct gops_pbdma pbdma;
+	/** Syncpoint hal ops. */
 	struct gops_sync sync;
+	/** Channel hal ops. */
 	struct gops_channel channel;
+	/** Tsg hal ops. */
 	struct gops_tsg tsg;
+	/** Usermode hal ops. */
 	struct gops_usermode usermode;
+	/** Engine status hal ops. */
 	struct gops_engine_status engine_status;
-	struct gops_pbdma_status pbdma_status;
+	/** Netlist hal ops. */
 	struct gops_netlist netlist;
+	/** Mm hal ops. */
 	struct gops_mm mm;
-	/*
-	 * This function is called to allocate secure memory (memory
-	 * that the CPU cannot see). The function should fill the
-	 * context buffer descriptor (especially fields destroy, sgt,
-	 * size).
-	 */
-	int (*secure_alloc)(struct gk20a *g, struct nvgpu_mem *desc_mem,
-			size_t size,
-			void (**fn)(struct gk20a *g, struct nvgpu_mem *mem));

 #ifdef CONFIG_NVGPU_DGPU
 	struct gops_pramin pramin;
 #endif
+	/** Therm hal ops. */
 	struct gops_therm therm;
+	/** Pmu hal ops. */
 	struct gops_pmu pmu;
+	/** Clock hal ops. */
 	struct gops_clk clk;
 #ifdef CONFIG_NVGPU_DGPU
 	struct gops_clk_mon clk_mon;
@@ -149,12 +153,11 @@ struct gpu_ops {
 #ifdef CONFIG_NVGPU_CLK_ARB
 	struct gops_clk_arb clk_arb;
 #endif
-	struct gops_pmu_perf pmu_perf;
 #ifdef CONFIG_NVGPU_DEBUGGER
 	struct gops_regops regops;
 #endif
+	/** Mc hal ops. */
 	struct gops_mc mc;
-	struct gops_debug debug;
 #ifdef CONFIG_NVGPU_DEBUGGER
 	struct gops_debugger debugger;
 	struct gops_perf perf;
@@ -164,10 +167,14 @@ struct gpu_ops {
 	struct gops_pm_reservation pm_reservation;
 #endif

+	/** Ops to get litter value corresponding to litter define. */
 	u32 (*get_litter_value)(struct gk20a *g, int value);
+	/** Ops to initialize gpu characteristics. */
 	int (*chip_init_gpu_characteristics)(struct gk20a *g);

+	/** Bus hal ops. */
 	struct gops_bus bus;
+	/** Ptimer hal ops. */
 	struct gops_ptimer ptimer;
 	struct gops_bios bios;
 #ifdef CONFIG_NVGPU_CYCLESTATS
@@ -176,16 +183,43 @@ struct gpu_ops {
 #ifdef CONFIG_NVGPU_DGPU
 	struct gops_xve xve;
 #endif
+	/** Falcon hal ops. */
 	struct gops_falcon falcon;
+	/** Fbp hal ops. */
 	struct gops_fbp fbp;
+	/** Priv ring hal ops. */
 	struct gops_priv_ring priv_ring;
-	struct gops_nvlink nvlink;
+	/** Top hal ops. */
 	struct gops_top top;
+/** @cond DOXYGEN_SHOULD_SKIP_THIS */
+	struct gops_sbr sbr;
+	struct gops_func func;
+	struct gops_nvdec nvdec;
+	struct gops_ramfc ramfc;
+	struct gops_ramin ramin;
+	struct gops_userd userd;
+	struct gops_engine engine;
+	struct gops_pbdma pbdma;
+	struct gops_pbdma_status pbdma_status;
+	/*
+	 * This function is called to allocate secure memory (memory
+	 * that the CPU cannot see). The function should fill the
+	 * context buffer descriptor (especially fields destroy, sgt,
+	 * size).
+	 */
+	int (*secure_alloc)(struct gk20a *g, struct nvgpu_mem *desc_mem,
+			size_t size,
+			void (**fn)(struct gk20a *g, struct nvgpu_mem *mem));
+	struct gops_pmu_perf pmu_perf;
+	struct gops_debug debug;
+	struct gops_nvlink nvlink;
 	struct gops_sec2 sec2;
 	struct gops_gsp gsp;
+/** @endcond */
 #ifdef CONFIG_NVGPU_TPC_POWERGATE
 	struct gops_tpc tpc;
 #endif
+	/** Wake up all threads waiting on semaphore wait. */
 	void (*semaphore_wakeup)(struct gk20a *g, bool post_events);

 	struct gops_grmgr grmgr;