Documentation/admin-guide/pm/intel_uncore_frequency_scaling.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2 .. include:: <isonum.txt>
   3
   4 ==============================
   5 Intel Uncore Frequency Scaling
   6 ==============================
   7
   8 :Copyright: |copy| 2022-2023 Intel Corporation
   9
  10 :Author: Srinivas Pandruvada <srinivas.pandruvada@linux.intel.com>
  11
  12 Introduction
  13 ------------
  14
  15 The uncore can consume significant amount of power in Intel's Xeon servers based
  16 on the workload characteristics. To optimize the total power and improve overall
  17 performance, SoCs have internal algorithms for scaling uncore frequency. These
  18 algorithms monitor workload usage of uncore and set a desirable frequency.
  19
  20 It is possible that users have different expectations of uncore performance and
  21 want to have control over it. The objective is similar to allowing users to set
  22 the scaling min/max frequencies via cpufreq sysfs to improve CPU performance.
  23 Users may have some latency sensitive workloads where they do not want any
  24 change to uncore frequency. Also, users may have workloads which require
  25 different core and uncore performance at distinct phases and they may want to
  26 use both cpufreq and the uncore scaling interface to distribute power and
  27 improve overall performance.
  28
  29 Sysfs Interface
  30 ---------------
  31
  32 To control uncore frequency, a sysfs interface is provided in the directory:
  33 `/sys/devices/system/cpu/intel_uncore_frequency/`.
  34
  35 There is one directory for each package and die combination as the scope of
  36 uncore scaling control is per die in multiple die/package SoCs or per
  37 package for single die per package SoCs. The name represents the
  38 scope of control. For example: 'package_00_die_00' is for package id 0 and
  39 die 0.
  40
  41 Each package_*_die_* contains the following attributes:
  42
  43 ``initial_max_freq_khz``
  44         Out of reset, this attribute represent the maximum possible frequency.
  45         This is a read-only attribute. If users adjust max_freq_khz,
  46         they can always go back to maximum using the value from this attribute.
  47
  48 ``initial_min_freq_khz``
  49         Out of reset, this attribute represent the minimum possible frequency.
  50         This is a read-only attribute. If users adjust min_freq_khz,
  51         they can always go back to minimum using the value from this attribute.
  52
  53 ``max_freq_khz``
  54         This attribute is used to set the maximum uncore frequency.
  55
  56 ``min_freq_khz``
  57         This attribute is used to set the minimum uncore frequency.
  58
  59 ``current_freq_khz``
  60         This attribute is used to get the current uncore frequency.
  61
  62 SoCs with TPMI (Topology Aware Register and PM Capsule Interface)
  63 -----------------------------------------------------------------
  64
  65 An SoC can contain multiple power domains with individual or collection
  66 of mesh partitions. This partition is called fabric cluster.
  67
  68 Certain type of meshes will need to run at the same frequency, they will
  69 be placed in the same fabric cluster. Benefit of fabric cluster is that it
  70 offers a scalable mechanism to deal with partitioned fabrics in a SoC.
  71
  72 The current sysfs interface supports controls at package and die level.
  73 This interface is not enough to support more granular control at
  74 fabric cluster level.
  75
  76 SoCs with the support of TPMI (Topology Aware Register and PM Capsule
  77 Interface), can have multiple power domains. Each power domain can
  78 contain one or more fabric clusters.
  79
  80 To represent controls at fabric cluster level in addition to the
  81 controls at package and die level (like systems without TPMI
  82 support), sysfs is enhanced. This granular interface is presented in the
  83 sysfs with directories names prefixed with "uncore". For example:
  84 uncore00, uncore01 etc.
  85
  86 The scope of control is specified by attributes "package_id", "domain_id"
  87 and "fabric_cluster_id" in the directory.
  88
  89 Attributes in each directory:
  90
  91 ``domain_id``
  92         This attribute is used to get the power domain id of this instance.
  93
  94 ``fabric_cluster_id``
  95         This attribute is used to get the fabric cluster id of this instance.
  96
  97 ``package_id``
  98         This attribute is used to get the package id of this instance.
  99
 100 The other attributes are same as presented at package_*_die_* level.
 101
 102 In most of current use cases, the "max_freq_khz" and "min_freq_khz"
 103 is updated at "package_*_die_*" level. This model will be still supported
 104 with the following approach:
 105
 106 When user uses controls at "package_*_die_*" level, then every fabric
 107 cluster is affected in that package and die. For example: user changes
 108 "max_freq_khz" in the package_00_die_00, then "max_freq_khz" for uncore*
 109 directory with the same package id will be updated. In this case user can
 110 still update "max_freq_khz" at each uncore* level, which is more restrictive.
 111 Similarly, user can update "min_freq_khz" at "package_*_die_*" level
 112 to apply at each uncore* level.
 113
 114 Support for "current_freq_khz" is available only at each fabric cluster
 115 level (i.e., in uncore* directory).