[PATCH v2 1/2] Documentation: admin-guide: pm: Document uncore frequency scaling

[PATCH v2 1/2] Documentation: admin-guide: pm: Document uncore frequency scaling

[Srinivas Pandruvada]

Added documentation to configure uncore frequency limits in Intel
Xeon processors.

Signed-off-by: Srinivas Pandruvada <srinivas.pandruvada@linux.intel.com>
---
v2
As suggested removed "===" (chapter) for Introduction and added two sections
"Introduction" and "Sysfs interface".

 .../pm/intel_uncore_frequency_scaling.rst     | 59 +++++++++++++++++++
 .../admin-guide/pm/working-state.rst          |  1 +
 2 files changed, 60 insertions(+)
 create mode 100644 Documentation/admin-guide/pm/intel_uncore_frequency_scaling.rst

diff --git a/Documentation/admin-guide/pm/intel_uncore_frequency_scaling.rst b/Documentation/admin-guide/pm/intel_uncore_frequency_scaling.rst
new file mode 100644
index 000000000000..a55cf68d77df
--- /dev/null
+++ b/Documentation/admin-guide/pm/intel_uncore_frequency_scaling.rst
@@ -0,0 +1,59 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
+
+==============================
+Intel Uncore Frequency Scaling
+==============================
+
+:Copyright: |copy| 2022 Intel Corporation
+
+:Author: Srinivas Pandruvada <srinivas.pandruvada@linux.intel.com>
+
+Introduction
+------------
+
+Uncore can consume significant amount of power in Intel's Xeon servers based
+on the workload characteristics. To optimize total power and improve overall
+performance, SoC has an internal algorithm for scaling uncore frequency. These
+algorithms monitor workload usage of uncore and set a desirable frequency.
+
+It is possible that users have different expectations of uncore performance and
+want to have control over it. The objective is similar to set scaling min/max
+frequencies using cpufreq sysfs to improve compute performance. Users may have
+some latency sensitive workload where they do not want any change to uncore
+frequency. Also, users may have workload which requires different core and
+uncore performance at distinct phases and they want to use both cpufreq and
+uncore scaling interface to distribute power and improve overall performance.
+
+Sysfs Interface
+---------------
+
+To control uncore frequency, a sysfs interface is provided in the directory:
+`/sys/devices/system/cpu/intel_uncore_frequency/`.
+
+There is one directory for each package and die combination as the scope of
+uncore scaling control is per die in multiple dies/package SoC or per
+package for single die per package SoC. The name represents the
+scope of control. For example: 'package_00_die_00' is for package id 0 and
+die 0 in it.
+
+Each package_*_die_* contains following attributes:
+
+``initial_max_freq_khz``
+	Out of reset, this attribute represent the maximum possible frequency.
+	This is a read only attribute. If users adjust max_freq_khz,
+	they can always go back to maximum using the value from this attribute.
+
+``initial_min_freq_khz``
+	Out of reset, this attribute represent the minimum possible frequency.
+	This is a read only attribute. If users adjust min_freq_khz,
+	they can always go back to minimum using the value from this attribute.
+
+``max_freq_khz``
+	This attribute is used to set the maximum uncore frequency.
+
+``min_freq_khz``
+	This attribute is used to set the minimum uncore frequency.
+
+``current_freq_khz``
+	This attribute is used to get the current uncore frequency.
diff --git a/Documentation/admin-guide/pm/working-state.rst b/Documentation/admin-guide/pm/working-state.rst
index 5d2757e2de65..ee45887811ff 100644
--- a/Documentation/admin-guide/pm/working-state.rst
+++ b/Documentation/admin-guide/pm/working-state.rst
@@ -15,3 +15,4 @@ Working-State Power Management
    cpufreq_drivers
    intel_epb
    intel-speed-select
+   intel_uncore_frequency_scaling
-- 
2.34.1

[PATCH v2 2/2] MAINTAINERS: Add additional file to uncore frequency control

[Srinivas Pandruvada]

Add additional Documentation file in the list of files.

Signed-off-by: Srinivas Pandruvada <srinivas.pandruvada@linux.intel.com>
---
New patch to add file to maintainers list.

 MAINTAINERS | 1 +
 1 file changed, 1 insertion(+)

diff --git a/MAINTAINERS b/MAINTAINERS
index dc4a1370ef1b..d36a51dee153 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -9891,6 +9891,7 @@ INTEL UNCORE FREQUENCY CONTROL
 M:	Srinivas Pandruvada <srinivas.pandruvada@linux.intel.com>
 L:	platform-driver-x86@vger.kernel.org
 S:	Maintained
+F:	Documentation/admin-guide/pm/intel_uncore_frequency_scaling.rst
 F:	drivers/platform/x86/intel/uncore-frequency.c
 
 INTEL VENDOR SPECIFIC EXTENDED CAPABILITIES DRIVER
-- 
2.34.1

Re: [PATCH v2 1/2] Documentation: admin-guide: pm: Document uncore frequency scaling

[Rafael J. Wysocki]

On Mon, Feb 28, 2022 at 8:58 PM Srinivas Pandruvada
<srinivas.pandruvada@linux.intel.com> wrote:
>
> Added documentation to configure uncore frequency limits in Intel
> Xeon processors.
>
> Signed-off-by: Srinivas Pandruvada <srinivas.pandruvada@linux.intel.com>
> ---
> v2
> As suggested removed "===" (chapter) for Introduction and added two sections
> "Introduction" and "Sysfs interface".
>
>  .../pm/intel_uncore_frequency_scaling.rst     | 59 +++++++++++++++++++
>  .../admin-guide/pm/working-state.rst          |  1 +
>  2 files changed, 60 insertions(+)
>  create mode 100644 Documentation/admin-guide/pm/intel_uncore_frequency_scaling.rst
>
> diff --git a/Documentation/admin-guide/pm/intel_uncore_frequency_scaling.rst b/Documentation/admin-guide/pm/intel_uncore_frequency_scaling.rst
> new file mode 100644
> index 000000000000..a55cf68d77df
> --- /dev/null
> +++ b/Documentation/admin-guide/pm/intel_uncore_frequency_scaling.rst
> @@ -0,0 +1,59 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +.. include:: <isonum.txt>
> +
> +==============================
> +Intel Uncore Frequency Scaling
> +==============================
> +
> +:Copyright: |copy| 2022 Intel Corporation
> +
> +:Author: Srinivas Pandruvada <srinivas.pandruvada@linux.intel.com>
> +
> +Introduction
> +------------
> +
> +Uncore can consume significant amount of power in Intel's Xeon servers based
> +on the workload characteristics. To optimize total power and improve overall
> +performance, SoC has an internal algorithm for scaling uncore frequency. These
> +algorithms monitor workload usage of uncore and set a desirable frequency.
> +
> +It is possible that users have different expectations of uncore performance and
> +want to have control over it. The objective is similar to set scaling min/max
> +frequencies using cpufreq sysfs to improve compute performance. Users may have
> +some latency sensitive workload where they do not want any change to uncore
> +frequency. Also, users may have workload which requires different core and
> +uncore performance at distinct phases and they want to use both cpufreq and
> +uncore scaling interface to distribute power and improve overall performance.
> +
> +Sysfs Interface
> +---------------
> +
> +To control uncore frequency, a sysfs interface is provided in the directory:
> +`/sys/devices/system/cpu/intel_uncore_frequency/`.
> +
> +There is one directory for each package and die combination as the scope of
> +uncore scaling control is per die in multiple dies/package SoC or per
> +package for single die per package SoC. The name represents the
> +scope of control. For example: 'package_00_die_00' is for package id 0 and
> +die 0 in it.
> +
> +Each package_*_die_* contains following attributes:
> +
> +``initial_max_freq_khz``
> +       Out of reset, this attribute represent the maximum possible frequency.
> +       This is a read only attribute. If users adjust max_freq_khz,
> +       they can always go back to maximum using the value from this attribute.
> +
> +``initial_min_freq_khz``
> +       Out of reset, this attribute represent the minimum possible frequency.
> +       This is a read only attribute. If users adjust min_freq_khz,
> +       they can always go back to minimum using the value from this attribute.
> +
> +``max_freq_khz``
> +       This attribute is used to set the maximum uncore frequency.
> +
> +``min_freq_khz``
> +       This attribute is used to set the minimum uncore frequency.
> +
> +``current_freq_khz``
> +       This attribute is used to get the current uncore frequency.
> diff --git a/Documentation/admin-guide/pm/working-state.rst b/Documentation/admin-guide/pm/working-state.rst
> index 5d2757e2de65..ee45887811ff 100644
> --- a/Documentation/admin-guide/pm/working-state.rst
> +++ b/Documentation/admin-guide/pm/working-state.rst
> @@ -15,3 +15,4 @@ Working-State Power Management
>     cpufreq_drivers
>     intel_epb
>     intel-speed-select
> +   intel_uncore_frequency_scaling
> --

Applied (with some cleanup of the wording in the document in some
places) as 5.18 material, along with the [2/2].

Thanks!