From 76f766d6ac36a921f7ac508161bfab299500fb4e Mon Sep 17 00:00:00 2001 From: shashank singh Date: Mon, 14 Dec 2020 10:58:07 +0530 Subject: [PATCH] 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 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 Reviewed-by: mobile promotions GVS: Gerrit_Virtual_Submit Tested-by: mobile promotions --- drivers/gpu/nvgpu/include/nvgpu/gk20a.h | 83 ++++++++++++++++++++-- drivers/gpu/nvgpu/include/nvgpu/gops/acr.h | 17 ++++- drivers/gpu/nvgpu/include/nvgpu/gops/clk.h | 14 +++- drivers/gpu/nvgpu/include/nvgpu/gops/fbp.h | 9 ++- drivers/gpu/nvgpu/include/nvgpu/gpu_ops.h | 82 ++++++++++++++------- 5 files changed, 174 insertions(+), 31 deletions(-) diff --git a/drivers/gpu/nvgpu/include/nvgpu/gk20a.h b/drivers/gpu/nvgpu/include/nvgpu/gk20a.h index 245435f17..683ee05f1 100644 --- 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) { diff --git a/drivers/gpu/nvgpu/include/nvgpu/gops/acr.h b/drivers/gpu/nvgpu/include/nvgpu/gops/acr.h index 6956fbf9e..134dc0682 100644 --- 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); }; diff --git a/drivers/gpu/nvgpu/include/nvgpu/gops/clk.h b/drivers/gpu/nvgpu/include/nvgpu/gops/clk.h index b0bc31873..d33e80dc7 100644 --- 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 { diff --git a/drivers/gpu/nvgpu/include/nvgpu/gops/fbp.h b/drivers/gpu/nvgpu/include/nvgpu/gops/fbp.h index 9636e88f6..61ea85f2b 100644 --- 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); }; diff --git a/drivers/gpu/nvgpu/include/nvgpu/gpu_ops.h b/drivers/gpu/nvgpu/include/nvgpu/gpu_ops.h index 1fc464dd0..7a3f81925 100644 --- 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,20 +183,47 @@ 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; }; -#endif /* NVGPU_GOPS_OPS_H */ \ No newline at end of file +#endif /* NVGPU_GOPS_OPS_H */