[PATCH] drm/amd/pm: add swsmu init documentation

[Ryan Taylor <Ryan.Taylor@amd.com>]

Documents functions used in swsmu initialization.

Signed-off-by: Ryan Taylor <Ryan.Taylor@amd.com>
Reviewed-by: Alex Deucher <alexander.deucher@amd.com>
---
 drivers/gpu/drm/amd/pm/swsmu/amdgpu_smu.c | 94 ++++++++++++++++++++++-
 1 file changed, 93 insertions(+), 1 deletion(-)

diff --git a/drivers/gpu/drm/amd/pm/swsmu/amdgpu_smu.c b/drivers/gpu/drm/amd/pm/swsmu/amdgpu_smu.c
index d80f7f8efdcd..82099cb3d00a 100644
--- a/drivers/gpu/drm/amd/pm/swsmu/amdgpu_smu.c
+++ b/drivers/gpu/drm/amd/pm/swsmu/amdgpu_smu.c
@@ -376,6 +376,15 @@ static int smu_get_driver_allowed_feature_mask(struct smu_context *smu)
 	return ret;
 }
 
+/**
+ * smu_set_funcs - Set ASIC specific SMU communication tools and data.
+ * @adev: amdgpu_device pointer
+ *
+ * Set hooks (&struct pptable_funcs), maps (&struct cmn2asic_mapping) and
+ * basic ASIC information (is_apu, od_enabled, etc.).
+ *
+ * Returns 0 on success, negative error code on failure.
+ */
 static int smu_set_funcs(struct amdgpu_device *adev)
 {
 	struct smu_context *smu = &adev->smu;
@@ -417,6 +426,15 @@ static int smu_set_funcs(struct amdgpu_device *adev)
 	return 0;
 }
 
+/**
+ * smu_early_init - Early init for the SMU IP block.
+ * @handle: amdgpu_device pointer
+ *
+ * Perform basic initialization of &struct smu_context. Set ASIC specific SMU
+ * communication tools and data using smu_set_funcs().
+ *
+ * Return: 0 on success, negative error code on failure.
+ */
 static int smu_early_init(void *handle)
 {
 	struct amdgpu_device *adev = (struct amdgpu_device *)handle;
@@ -424,10 +442,12 @@ static int smu_early_init(void *handle)
 
 	smu->adev = adev;
 	smu->pm_enabled = !!amdgpu_dpm;
+	/* Assume ASIC is not an APU until updated in smu_set_funcs(). */
 	smu->is_apu = false;
 	mutex_init(&smu->mutex);
 	mutex_init(&smu->smu_baco.mutex);
 	smu->smu_baco.state = SMU_BACO_STATE_EXIT;
+	/* Disable baco support until the SMU engine is running. */
 	smu->smu_baco.platform_support = false;
 
 	return smu_set_funcs(adev);
@@ -472,6 +492,17 @@ static int smu_set_default_dpm_table(struct smu_context *smu)
 	return ret;
 }
 
+
+/**
+ * smu_late_init - Finish setting up the SMU IP block.
+ * @adev: amdgpu_device pointer
+ *
+ * Setup SMU tables/values used by other driver subsystems and in userspace
+ * (Overdrive, UMD power states, etc.). Perform final SMU configuration (set
+ * performance level, update display config etc.).
+ *
+ * Returns 0 on success, negative error code on failure.
+ */
 static int smu_late_init(void *handle)
 {
 	struct amdgpu_device *adev = (struct amdgpu_device *)handle;
@@ -514,6 +545,8 @@ static int smu_late_init(void *handle)
 
 	smu_get_fan_parameters(smu);
 
+	/* Sets performance level, power profile mode and display
+	 * configuration. */
 	smu_handle_task(&adev->smu,
 			smu->smu_dpm.dpm_level,
 			AMD_PP_TASK_COMPLETE_INIT,
@@ -601,7 +634,7 @@ static int smu_fini_fb_allocations(struct smu_context *smu)
 /**
  * smu_alloc_memory_pool - allocate memory pool in the system memory
  *
- * @smu: amdgpu_device pointer
+ * @smu: smu_context pointer
  *
  * This memory pool will be used for SMC use and msg SetSystemVirtualDramAddr
  * and DramLogSetDramAddr can notify it changed.
@@ -701,6 +734,15 @@ static void smu_free_dummy_read_table(struct smu_context *smu)
 	memset(dummy_read_1_table, 0, sizeof(struct smu_table));
 }
 
+/**
+ * smu_smc_table_sw_init -  Initialize shared driver/SMU communication tools.
+ * @smu: smu_context pointer
+ *
+ * Allocate VRAM/DRAM for shared memory objects (SMU tables, memory pool, etc.).
+ * Initialize i2c.
+ *
+ * Returns 0 on success, negative error code on failure.
+ */
 static int smu_smc_table_sw_init(struct smu_context *smu)
 {
 	int ret;
@@ -799,6 +841,18 @@ static void smu_interrupt_work_fn(struct work_struct *work)
 	mutex_unlock(&smu->mutex);
 }
 
+/**
+ * smu_sw_init - Software init for the SMU IP block.
+ * @handle: amdgpu_device pointer
+ *
+ * Configure &struct smu_context with boot default performance profiles (power
+ * profile, workload, etc.) and power savings optimizations (powergate
+ * VCN/JPEG). Request the SMU's firmware from the kernel. Initialize features,
+ * locks, and kernel work queues. Initialize driver/SMU communication tools
+ * using smu_smc_table_sw_init(). Register the interrupt handler.
+ *
+ * Returns 0 on success, negative error code on failure.
+ */
 static int smu_sw_init(void *handle)
 {
 	struct amdgpu_device *adev = (struct amdgpu_device *)handle;
@@ -820,6 +874,7 @@ static int smu_sw_init(void *handle)
 	INIT_WORK(&smu->interrupt_work, smu_interrupt_work_fn);
 	atomic64_set(&smu->throttle_int_counter, 0);
 	smu->watermarks_bitmap = 0;
+
 	smu->power_profile_mode = PP_SMC_POWER_PROFILE_BOOTUP_DEFAULT;
 	smu->default_power_profile_mode = PP_SMC_POWER_PROFILE_BOOTUP_DEFAULT;
 
@@ -914,6 +969,18 @@ static int smu_get_thermal_temperature_range(struct smu_context *smu)
 	return ret;
 }
 
+/**
+ * smu_smc_hw_setup - Configure SMU hardware for boot/resume.
+ * @smu: smu_context pointer
+ *
+ * Configure the following SMU hardware parameters: voltage frequency curve,
+ * power play table, features, system PCIe capabilities and shared memory
+ * locations. Use the configured SMU to setup thermal interrupts and populate
+ * the DPM tables. Finally, prepare the SMU for display component
+ * synchronization.
+ *
+ * Returns 0 on success, negative error code on failure.
+ */
 static int smu_smc_hw_setup(struct smu_context *smu)
 {
 	struct amdgpu_device *adev = smu->adev;
@@ -929,6 +996,7 @@ static int smu_smc_hw_setup(struct smu_context *smu)
 		return ret;
 	}
 
+	/* Disables display tracking. */
 	ret = smu_init_display_count(smu, 0);
 	if (ret) {
 		dev_info(adev->dev, "Failed to pre-set display count as 0!\n");
@@ -991,6 +1059,7 @@ static int smu_smc_hw_setup(struct smu_context *smu)
 	if (!smu_is_dpm_running(smu))
 		dev_info(adev->dev, "dpm has been disabled\n");
 
+	/* Get the system's PCIE capabilities. */
 	if (adev->pm.pcie_gen_mask & CAIL_PCIE_LINK_SPEED_SUPPORT_GEN4)
 		pcie_gen = 3;
 	else if (adev->pm.pcie_gen_mask & CAIL_PCIE_LINK_SPEED_SUPPORT_GEN3)
@@ -1061,6 +1130,16 @@ static int smu_smc_hw_setup(struct smu_context *smu)
 	return ret;
 }
 
+/**
+ * smu_start_smc_engine - Start the SMU engine.
+ * @smu: smu_context pointer
+ *
+ * Load SMU firmware if not loaded by PSP. Verify that firmware was
+ * loaded successfully. Check SMU firmware interface version (version mismatch
+ * is not a critical failure).
+ *
+ * Returns 0 on success, negative error code on failure.
+ */
 static int smu_start_smc_engine(struct smu_context *smu)
 {
 	struct amdgpu_device *adev = smu->adev;
@@ -1095,6 +1174,17 @@ static int smu_start_smc_engine(struct smu_context *smu)
 	return ret;
 }
 
+/**
+ * smu_hw_init - Hardware init for the SMU IP block.
+ * @handle: amdgpu_device pointer
+ *
+ * Start the SMU engine using smu_start_smc_engine(). Setup SMU configuration
+ * information (pptable, boot values, features). Configure SMU hardware for
+ * boot/resume using smu_smc_hw_setup(). Get table of maximum sustainable clock
+ * speeds from the SMU.
+ *
+ * Returns 0 on success, negative error code on failure.
+ */
 static int smu_hw_init(void *handle)
 {
 	int ret;
@@ -1112,6 +1202,8 @@ static int smu_hw_init(void *handle)
 		return ret;
 	}
 
+	/* APUs boot with several components turned off to save power. Enable
+	 * these IP blocks so that APUs are in the same state as other ASICs. */
 	if (smu->is_apu) {
 		smu_powergate_sdma(&adev->smu, false);
 		smu_dpm_set_vcn_enable(smu, true);
-- 
2.29.2

_______________________________________________
amd-gfx mailing list
amd-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/amd-gfx