Documentation: admin-guide: pm: Document intel_idle C1 demotion

Document the intel_idle driver sysfs file for enabling/disabling C1
demotion.

Signed-off-by: Artem Bityutskiy <artem.bityutskiy@linux.intel.com>
Link: https://patch.msgid.link/20250317135541.1471754-3-dedekind1@gmail.com
Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>

diff --git a/Documentation/admin-guide/pm/intel_idle.rst b/Documentation/admin-guide/pm/intel_idle.rst
index 5940528146eb00c64fbd9484e268fa46c0ecbb74..ed6f055d4b148e5beda28bf1e5257e2ea0e120d4 100644 (file)
--- a/Documentation/admin-guide/pm/intel_idle.rst
+++ b/Documentation/admin-guide/pm/intel_idle.rst
@@ -38,6 +38,27 @@ instruction at all.
 only way to pass early-configuration-time parameters to it is via the kernel
 command line.
 
+Sysfs Interface
+===============
+
+The ``intel_idle`` driver exposes the following ``sysfs`` attributes in
+``/sys/devices/system/cpu/cpuidle/``:
+
+``intel_c1_demotion``
+       Enable or disable C1 demotion for all CPUs in the system. This file is
+       only exposed on platforms that support the C1 demotion feature and where
+       it was tested. Value 0 means that C1 demotion is disabled, value 1 means
+       that it is enabled. Write 0 or 1 to disable or enable C1 demotion for
+       all CPUs.
+
+       The C1 demotion feature involves the platform firmware demoting deep
+       C-state requests from the OS (e.g., C6 requests) to C1. The idea is that
+       firmware monitors CPU wake-up rate, and if it is higher than a
+       platform-specific threshold, the firmware demotes deep C-state requests
+       to C1. For example, Linux requests C6, but firmware noticed too many
+       wake-ups per second, and it keeps the CPU in C1. When the CPU stays in
+       C1 long enough, the platform promotes it back to C6. This may improve
+       some workloads' performance, but it may also increase power consumption.
 
 .. _intel-idle-enumeration-of-states: