[PATCH v2 1/2] Documentation: ACPI: Documentation for Fan performance states

[Srinivas Pandruvada]

Added documentation for performance states information for the ACPI
Fan object.

Signed-off-by: Srinivas Pandruvada <srinivas.pandruvada@xxxxxxxxxxxxxxx>
---
 .../acpi/fan_performance_states.rst           | 65 +++++++++++++++++++
 Documentation/admin-guide/acpi/index.rst      |  1 +
 2 files changed, 66 insertions(+)
 create mode 100644 Documentation/admin-guide/acpi/fan_performance_states.rst

diff --git a/Documentation/admin-guide/acpi/fan_performance_states.rst b/Documentation/admin-guide/acpi/fan_performance_states.rst
new file mode 100644
index 000000000000..91f10738e158
--- /dev/null
+++ b/Documentation/admin-guide/acpi/fan_performance_states.rst
@@ -0,0 +1,65 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===========================
+ACPI Fan Performance States
+===========================
+
+When the optional object _FPS is present for ACPI devices PNP0C0B or INT3404,
+additional attributes are displayed under acpi device object. These attributes
+display information about each performance state.
+
+For more details about ACPI Fan _FPS please refer to the ACPI specification at:
+
+http://uefi.org/specifications
+
+Example display for INT3404 ACPI device folder::
+
+ $ ls -l /sys/bus/acpi/devices/INT3404:00/
+ total 0
+ -r--r--r-- 1 root root 4096 Dec 13 20:38 state0
+ -r--r--r-- 1 root root 4096 Dec 13 20:38 state1
+ -r--r--r-- 1 root root 4096 Dec 13 20:38 state10
+ -r--r--r-- 1 root root 4096 Dec 13 20:38 state11
+ -r--r--r-- 1 root root 4096 Dec 13 20:38 state2
+ -r--r--r-- 1 root root 4096 Dec 13 20:38 state3
+ -r--r--r-- 1 root root 4096 Dec 13 20:38 state4
+ -r--r--r-- 1 root root 4096 Dec 13 20:38 state5
+ -r--r--r-- 1 root root 4096 Dec 13 20:38 state6
+ -r--r--r-- 1 root root 4096 Dec 13 20:38 state7
+ -r--r--r-- 1 root root 4096 Dec 13 20:38 state8
+ -r--r--r-- 1 root root 4096 Dec 13 20:38 state9
+ -r--r--r-- 1 root root 4096 Dec 13 01:00 status
+ ...
+ ...
+
+In the above example, each of the state* attribute represent one performance
+state. Each performance state contains information about the properties of a
+state in the following format:
+
+control_percent:trip_point_index:speed_rpm:noise_level_mdb:power_mw
+
+For example::
+
+ $cat /sys/bus/acpi/devices/INT3404:00/state1
+ 25:0:3200:12500:1250
+
+Description of properties:
+
+* control_percent: Indicates the value to be used to set the fan speed to a
+specific level using the _FSL object. The value here is from 0-100 percent.
+
+* trip_point_index: The active cooling trip point number that corresponds to this
+performance state. The range is from 0-9.
+
+* speed_rpm: Indicates the speed of the fan in revolutions per minute.
+
+* noise_level_mdb: Indicates the audible noise emitted by the fan. By the
+specification the value represents the noise in 10ths of decibels. Here
+it is multiplied with 100 to present in milli-db, to avoid loss of
+precision.
+
+* power_mw: Indicates the power consumption in milliwatts.
+
+When the fields are not populated or invalid in the configuration,
+"not-defined" is displayed.
+
diff --git a/Documentation/admin-guide/acpi/index.rst b/Documentation/admin-guide/acpi/index.rst
index 4d13eeea1eca..71277689ad97 100644
--- a/Documentation/admin-guide/acpi/index.rst
+++ b/Documentation/admin-guide/acpi/index.rst
@@ -12,3 +12,4 @@ the Linux ACPI support.
    dsdt-override
    ssdt-overlays
    cppc_sysfs
+   fan_performance_states
-- 
2.17.2