From: Lucas De Marchi Date: Wed, 29 Oct 2025 23:45:08 +0000 (-0700) Subject: drm/xe: Improve freq and throttle documentation X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=47c3ea3359d14ffa4ff94511ae905978d86bb5dd;p=thirdparty%2Fkernel%2Flinux.git drm/xe: Improve freq and throttle documentation Add xe_gt_throttle under the "GT Frequency Management" and improve the narrative making sure the documentation for both *_freq and throttle/* attributes follow the same style. Reviewed-by: Raag Jadav Link: https://patch.msgid.link/20251029-gt-throttle-cri-v3-6-d1f5abbb8114@intel.com Signed-off-by: Lucas De Marchi --- diff --git a/Documentation/gpu/xe/xe_gt_freq.rst b/Documentation/gpu/xe/xe_gt_freq.rst index c0811200e3275..182d6aabeee18 100644 --- a/Documentation/gpu/xe/xe_gt_freq.rst +++ b/Documentation/gpu/xe/xe_gt_freq.rst @@ -7,6 +7,9 @@ Xe GT Frequency Management .. kernel-doc:: drivers/gpu/drm/xe/xe_gt_freq.c :doc: Xe GT Frequency Management +.. kernel-doc:: drivers/gpu/drm/xe/xe_gt_throttle.c + :doc: Xe GT Throttle + Internal API ============ diff --git a/drivers/gpu/drm/xe/xe_gt_freq.c b/drivers/gpu/drm/xe/xe_gt_freq.c index e88f113226bca..849ea6c86e8e2 100644 --- a/drivers/gpu/drm/xe/xe_gt_freq.c +++ b/drivers/gpu/drm/xe/xe_gt_freq.c @@ -29,24 +29,26 @@ * PCODE is the ultimate decision maker of the actual running frequency, based * on thermal and other running conditions. * - * Xe's Freq provides a sysfs API for frequency management: + * Xe's Freq provides a sysfs API for frequency management under + * ``/tile#/gt#/freq0/`` directory. * - * device/tile#/gt#/freq0/_freq *read-only* files: + * **Read-only** attributes: * - * - act_freq: The actual resolved frequency decided by PCODE. - * - cur_freq: The current one requested by GuC PC to the PCODE. - * - rpn_freq: The Render Performance (RP) N level, which is the minimal one. - * - rpa_freq: The Render Performance (RP) A level, which is the achievable one. - * Calculated by PCODE at runtime based on multiple running conditions - * - rpe_freq: The Render Performance (RP) E level, which is the efficient one. - * Calculated by PCODE at runtime based on multiple running conditions - * - rp0_freq: The Render Performance (RP) 0 level, which is the maximum one. + * - ``act_freq``: The actual resolved frequency decided by PCODE. + * - ``cur_freq``: The current one requested by GuC PC to the PCODE. + * - ``rpn_freq``: The Render Performance (RP) N level, which is the minimal one. + * - ``rpa_freq``: The Render Performance (RP) A level, which is the achievable one. + * Calculated by PCODE at runtime based on multiple running conditions + * - ``rpe_freq``: The Render Performance (RP) E level, which is the efficient one. + * Calculated by PCODE at runtime based on multiple running conditions + * - ``rp0_freq``: The Render Performance (RP) 0 level, which is the maximum one. * - * device/tile#/gt#/freq0/_freq *read-write* files: + * **Read-write** attributes: * - * - min_freq: Min frequency request. - * - max_freq: Max frequency request. - * If max <= min, then freq_min becomes a fixed frequency request. + * - ``min_freq``: Min frequency request. + * - ``max_freq``: Max frequency request. + * If max <= min, then freq_min becomes a fixed frequency + * request. */ static struct xe_guc_pc * diff --git a/drivers/gpu/drm/xe/xe_gt_throttle.c b/drivers/gpu/drm/xe/xe_gt_throttle.c index b5317cf714e2e..8647d2c997347 100644 --- a/drivers/gpu/drm/xe/xe_gt_throttle.c +++ b/drivers/gpu/drm/xe/xe_gt_throttle.c @@ -17,35 +17,41 @@ /** * DOC: Xe GT Throttle * - * Provides sysfs entries and other helpers for frequency throttle reasons in GT - * - * device/gt#/freq0/throttle/status - Overall status - * device/gt#/freq0/throttle/reason_pl1 - Frequency throttle due to PL1 - * device/gt#/freq0/throttle/reason_pl2 - Frequency throttle due to PL2 - * device/gt#/freq0/throttle/reason_pl4 - Frequency throttle due to PL4, Iccmax etc. - * device/gt#/freq0/throttle/reason_thermal - Frequency throttle due to thermal - * device/gt#/freq0/throttle/reason_prochot - Frequency throttle due to prochot - * device/gt#/freq0/throttle/reason_ratl - Frequency throttle due to RATL - * device/gt#/freq0/throttle/reason_vr_thermalert - Frequency throttle due to VR THERMALERT - * device/gt#/freq0/throttle/reason_vr_tdc - Frequency throttle due to VR TDC + * The GT frequency may be throttled by hardware/firmware for various reasons + * that are provided through attributes under the ``freq0/throttle/`` directory. + * Their availability depend on the platform and some may not be visible if that + * reason is not available. * * The following attributes are available on Crescent Island platform: - * device/gt#/freq0/throttle/status - Overall throttle status - * device/gt#/freq0/throttle/reason_pl1 - Frequency throttle due to package PL1 - * device/gt#/freq0/throttle/reason_pl2 - Frequency throttle due to package PL2 - * device/gt#/freq0/throttle/reason_pl4 - Frequency throttle due to PL4 - * device/gt#/freq0/throttle/reason_prochot - Frequency throttle due to prochot - * device/gt#/freq0/throttle/reason_soc_thermal - Frequency throttle due to SoC thermal - * device/gt#/freq0/throttle/reason_mem_thermal - Frequency throttle due to memory thermal - * device/gt#/freq0/throttle/reason_vr_thermal - Frequency throttle due to VR thermal - * device/gt#/freq0/throttle/reason_iccmax - Frequency throttle due to ICCMAX - * device/gt#/freq0/throttle/reason_ratl - Frequency throttle due to RATL thermal algorithm - * device/gt#/freq0/throttle/reason_soc_avg_thermal - Frequency throttle due to SoC average temp - * device/gt#/freq0/throttle/reason_fastvmode - Frequency throttle due to VR is hitting FastVMode - * device/gt#/freq0/throttle/reason_psys_pl1 - Frequency throttle due to PSYS PL1 - * device/gt#/freq0/throttle/reason_psys_pl2 - Frequency throttle due to PSYS PL2 - * device/gt#/freq0/throttle/reason_p0_freq - Frequency throttle due to P0 frequency - * device/gt#/freq0/throttle/reason_psys_crit - Frequency throttle due to PSYS critical + * + * - ``status``: Overall throttle status + * - ``reason_pl1``: package PL1 + * - ``reason_pl2``: package PL2 + * - ``reason_pl4``: package PL4 + * - ``reason_prochot``: prochot + * - ``reason_soc_thermal``: SoC thermal + * - ``reason_mem_thermal``: Memory thermal + * - ``reason_vr_thermal``: VR thermal + * - ``reason_iccmax``: ICCMAX + * - ``reason_ratl``: RATL thermal algorithm + * - ``reason_soc_avg_thermal``: SoC average temp + * - ``reason_fastvmode``: VR is hitting FastVMode + * - ``reason_psys_pl1``: PSYS PL1 + * - ``reason_psys_pl2``: PSYS PL2 + * - ``reason_p0_freq``: P0 frequency + * - ``reason_psys_crit``: PSYS critical + * + * Other platforms support the following reasons: + * + * - ``status``: Overall status + * - ``reason_pl1``: package PL1 + * - ``reason_pl2``: package PL2 + * - ``reason_pl4``: package PL4, Iccmax etc. + * - ``reason_thermal``: thermal + * - ``reason_prochot``: prochot + * - ``reason_ratl``: RATL hermal algorithm + * - ``reason_vr_thermalert``: VR THERMALERT + * - ``reason_vr_tdc``: VR TDC */ static struct xe_gt *dev_to_gt(struct device *dev)