Commit 47c3ea33 authored by Lucas De Marchi's avatar Lucas De Marchi
Browse files

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: default avatarRaag Jadav <raag.jadav@intel.com>
Link: https://patch.msgid.link/20251029-gt-throttle-cri-v3-6-d1f5abbb8114@intel.com


Signed-off-by: default avatarLucas De Marchi <lucas.demarchi@intel.com>
parent 191db84b

Documentation/gpu/xe/xe_gt_freq.rst

+3 −0
Original line number Diff line number Diff line
@@ -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

============

drivers/gpu/drm/xe/xe_gt_freq.c

+16 −14
Original line number Diff line number Diff line
@@ -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

 * ``<device>/tile#/gt#/freq0/`` directory.

 *

 * device/tile#/gt#/freq0/<item>_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.

 * - ``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.

 * - ``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.

 * - ``rp0_freq``: The Render Performance (RP) 0 level, which is the maximum one.

 *

 * device/tile#/gt#/freq0/<item>_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 *

drivers/gpu/drm/xe/xe_gt_throttle.c

+33 −27
Original line number Diff line number Diff line
@@ -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)