diff mbox series

[v6,1/3] Documentation: Add documentation for new platform_profile sysfs attribute

Message ID 20201211020630.305905-1-markpearson@lenovo.com
State Superseded
Headers show
Series [v6,1/3] Documentation: Add documentation for new platform_profile sysfs attribute | expand

Commit Message

Mark Pearson Dec. 11, 2020, 2:06 a.m. UTC
On modern systems the platform performance, temperature, fan and other
hardware related characteristics are often dynamically configurable. The
profile is often automatically adjusted to the load by some
automatic-mechanism (which may very well live outside the kernel).

These auto platform-adjustment mechanisms often can be configured with
one of several 'platform-profiles', with either a bias towards low-power
consumption or towards performance (and higher power consumption and
thermals).

Introduce a new platform_profile sysfs API which offers a generic API for
selecting the performance-profile of these automatic-mechanisms.

Co-developed-by: Mark Pearson <markpearson@lenovo.com>
Signed-off-by: Mark Pearson <markpearson@lenovo.com>
Signed-off-by: Hans de Goede <hdegoede@redhat.com>
---
Changes in v2:
 - updated to rst format
Changes in v3, v4, v5
 - version bump along with rest of patch series
Changes in v6:
 - Split sysfs-platform_profile.rs into ABI text and then admin guide in
   userspace-api section. Hope this is correct - I'm guessing a bit.

 .../ABI/testing/sysfs-platform_profile        | 24 +++++++++++
 Documentation/userspace-api/index.rst         |  1 +
 .../userspace-api/sysfs-platform_profile.rst  | 43 +++++++++++++++++++
 3 files changed, 68 insertions(+)
 create mode 100644 Documentation/ABI/testing/sysfs-platform_profile
 create mode 100644 Documentation/userspace-api/sysfs-platform_profile.rst

Comments

Rafael J. Wysocki Dec. 16, 2020, 6:34 p.m. UTC | #1
On Fri, Dec 11, 2020 at 3:15 AM Mark Pearson <markpearson@lenovo.com> wrote:
>

> On modern systems the platform performance, temperature, fan and other

> hardware related characteristics are often dynamically configurable. The

> profile is often automatically adjusted to the load by some

> automatic-mechanism (which may very well live outside the kernel).

>

> These auto platform-adjustment mechanisms often can be configured with

> one of several 'platform-profiles', with either a bias towards low-power

> consumption or towards performance (and higher power consumption and

> thermals).

>

> Introduce a new platform_profile sysfs API which offers a generic API for

> selecting the performance-profile of these automatic-mechanisms.

>

> Co-developed-by: Mark Pearson <markpearson@lenovo.com>

> Signed-off-by: Mark Pearson <markpearson@lenovo.com>

> Signed-off-by: Hans de Goede <hdegoede@redhat.com>

> ---

> Changes in v2:

>  - updated to rst format

> Changes in v3, v4, v5

>  - version bump along with rest of patch series

> Changes in v6:

>  - Split sysfs-platform_profile.rs into ABI text and then admin guide in

>    userspace-api section. Hope this is correct - I'm guessing a bit.

>

>  .../ABI/testing/sysfs-platform_profile        | 24 +++++++++++

>  Documentation/userspace-api/index.rst         |  1 +

>  .../userspace-api/sysfs-platform_profile.rst  | 43 +++++++++++++++++++

>  3 files changed, 68 insertions(+)

>  create mode 100644 Documentation/ABI/testing/sysfs-platform_profile

>  create mode 100644 Documentation/userspace-api/sysfs-platform_profile.rst

>

> diff --git a/Documentation/ABI/testing/sysfs-platform_profile b/Documentation/ABI/testing/sysfs-platform_profile

> new file mode 100644

> index 000000000000..5ac14268585f

> --- /dev/null

> +++ b/Documentation/ABI/testing/sysfs-platform_profile

> @@ -0,0 +1,24 @@

> +What:          /sys/firmware/acpi/platform_profile_choices

> +Date:          October 2020

> +Contact:       Hans de Goede <hdegoede@redhat.com>

> +Description:   This file contains a space-separated list of profiles supported for this device.

> +

> +               Drivers must use the following standard profile-names:

> +

> +               ============    ============================================

> +               low-power       Low power consumption

> +               cool            Cooler operation

> +               quiet           Quieter operation

> +               balanced        Balance between low power consumption and performance

> +               performance     High performance operation

> +               ============    ============================================

> +

> +               Userspace may expect drivers to offer more than one of these

> +               standard profile names.

> +

> +What:          /sys/firmware/acpi/platform_profile

> +Date:          October 2020

> +Contact:       Hans de Goede <hdegoede@redhat.com>

> +Description:   Reading this file gives the current selected profile for this

> +               device. Writing this file with one of the strings from

> +               available_profiles changes the profile to the new value.


IIUC s/available_profiles/platform_profile_choices/

> diff --git a/Documentation/userspace-api/index.rst b/Documentation/userspace-api/index.rst

> index acd2cc2a538d..d29b020e5622 100644

> --- a/Documentation/userspace-api/index.rst

> +++ b/Documentation/userspace-api/index.rst

> @@ -24,6 +24,7 @@ place where this information is gathered.

>     ioctl/index

>     iommu

>     media/index

> +   sysfs-platform_profile

>

>  .. only::  subproject and html

>

> diff --git a/Documentation/userspace-api/sysfs-platform_profile.rst b/Documentation/userspace-api/sysfs-platform_profile.rst

> new file mode 100644

> index 000000000000..56639d218003

> --- /dev/null

> +++ b/Documentation/userspace-api/sysfs-platform_profile.rst

> @@ -0,0 +1,43 @@

> +=====================================================================

> +Platform Profile Selection (e.g. /sys/firmware/acpi/platform_profile)

> +=====================================================================

> +

> +On modern systems the platform performance, temperature, fan and other

> +hardware related characteristics are often dynamically configurable. The

> +profile is often automatically adjusted to the load by some


After reading this one more time it looks to me like referring to the
profile here is premature, it needs to be defined first.

Maybe say "The platform configuration is often ..."

Iit is also unclear what "the load" means here, so I would say
something like "adjusted to the current conditions" to avoid using
that term.

> +automatic mechanism (which may very well live outside the kernel).

> +

> +These auto platform adjustment mechanisms often can be configured with

> +one of several platform profiles, with either a bias towards low power

> +operation or towards performance.

> +

> +The purpose of the platform_profile attribute is to offer a generic sysfs

> +API for selecting the platform profile of these automatic mechanisms.

> +

> +Note that this API is only for selecting the platform profile, it is

> +NOT a goal of this API to allow monitoring the resulting performance

> +characteristics. Monitoring performance is best done with device/vendor

> +specific tools such as e.g. turbostat.

> +

> +Specifically when selecting a high performance profile the actual achieved

> +performance may be limited by various factors such as: the heat generated

> +by other components, room temperature, free air flow at the bottom of a

> +laptop, etc. It is explicitly NOT a goal of this API to let userspace know

> +about any sub-optimal conditions which are impeding reaching the requested

> +performance level.

> +

> +Since numbers on their own cannot represent the multiple variables that a

> +profile will adjust (power consumption, heat generation, etc) this API

> +uses strings to describe the various profiles. To make sure that userspace

> +gets a consistent experience the sysfs-platform_profile ABI document defines

> +a fixed set of profile names. Drivers *must* map their internal profile

> +representation onto this fixed set.

> +

> +If there is no good match when mapping then a new profile name may be

> +added. Drivers which wish to introduce new profile names must:

> +

> + 1. Explain why the existing profile names canot be used.

> + 2. Add the new profile name, along with a clear description of the

> +    expected behaviour, to the sysfs-platform_profile ABI documentation.

> +

> +

> --
Mark Pearson Dec. 16, 2020, 7:26 p.m. UTC | #2
Hi Rafael,

On 16/12/2020 13:34, Rafael J. Wysocki wrote:
> On Fri, Dec 11, 2020 at 3:15 AM Mark Pearson <markpearson@lenovo.com> wrote:

>>

<snip>
>>

>> diff --git a/Documentation/ABI/testing/sysfs-platform_profile b/Documentation/ABI/testing/sysfs-platform_profile

>> new file mode 100644

>> index 000000000000..5ac14268585f

>> --- /dev/null

>> +++ b/Documentation/ABI/testing/sysfs-platform_profile

>> @@ -0,0 +1,24 @@

>> +What:          /sys/firmware/acpi/platform_profile_choices

>> +Date:          October 2020

>> +Contact:       Hans de Goede <hdegoede@redhat.com>

>> +Description:   This file contains a space-separated list of profiles supported for this device.

>> +

>> +               Drivers must use the following standard profile-names:

>> +

>> +               ============    ============================================

>> +               low-power       Low power consumption

>> +               cool            Cooler operation

>> +               quiet           Quieter operation

>> +               balanced        Balance between low power consumption and performance

>> +               performance     High performance operation

>> +               ============    ============================================

>> +

>> +               Userspace may expect drivers to offer more than one of these

>> +               standard profile names.

>> +

>> +What:          /sys/firmware/acpi/platform_profile

>> +Date:          October 2020

>> +Contact:       Hans de Goede <hdegoede@redhat.com>

>> +Description:   Reading this file gives the current selected profile for this

>> +               device. Writing this file with one of the strings from

>> +               available_profiles changes the profile to the new value.

> 

> IIUC s/available_profiles/platform_profile_choices/

Yep - I missed this one. Thank you, I'll update
> 

>> diff --git a/Documentation/userspace-api/index.rst b/Documentation/userspace-api/index.rst

>> index acd2cc2a538d..d29b020e5622 100644

>> --- a/Documentation/userspace-api/index.rst

>> +++ b/Documentation/userspace-api/index.rst

>> @@ -24,6 +24,7 @@ place where this information is gathered.

>>     ioctl/index

>>     iommu

>>     media/index

>> +   sysfs-platform_profile

>>

>>  .. only::  subproject and html

>>

>> diff --git a/Documentation/userspace-api/sysfs-platform_profile.rst b/Documentation/userspace-api/sysfs-platform_profile.rst

>> new file mode 100644

>> index 000000000000..56639d218003

>> --- /dev/null

>> +++ b/Documentation/userspace-api/sysfs-platform_profile.rst

>> @@ -0,0 +1,43 @@

>> +=====================================================================

>> +Platform Profile Selection (e.g. /sys/firmware/acpi/platform_profile)

>> +=====================================================================

>> +

>> +On modern systems the platform performance, temperature, fan and other

>> +hardware related characteristics are often dynamically configurable. The

>> +profile is often automatically adjusted to the load by some

> 

> After reading this one more time it looks to me like referring to the

> profile here is premature, it needs to be defined first.

> 

> Maybe say "The platform configuration is often ..."

> 

> Iit is also unclear what "the load" means here, so I would say

> something like "adjusted to the current conditions" to avoid using

> that term.

I'm good with both those suggestions. Thank you. I'll update

Mark
diff mbox series

Patch

diff --git a/Documentation/ABI/testing/sysfs-platform_profile b/Documentation/ABI/testing/sysfs-platform_profile
new file mode 100644
index 000000000000..5ac14268585f
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-platform_profile
@@ -0,0 +1,24 @@ 
+What:		/sys/firmware/acpi/platform_profile_choices
+Date:		October 2020
+Contact:	Hans de Goede <hdegoede@redhat.com>
+Description:	This file contains a space-separated list of profiles supported for this device.
+
+		Drivers must use the following standard profile-names:
+
+		============	============================================
+		low-power	Low power consumption
+		cool		Cooler operation
+		quiet		Quieter operation
+		balanced	Balance between low power consumption and performance
+		performance	High performance operation
+		============	============================================
+
+		Userspace may expect drivers to offer more than one of these
+		standard profile names.
+
+What:		/sys/firmware/acpi/platform_profile
+Date:		October 2020
+Contact:	Hans de Goede <hdegoede@redhat.com>
+Description:	Reading this file gives the current selected profile for this
+		device. Writing this file with one of the strings from
+		available_profiles changes the profile to the new value.
diff --git a/Documentation/userspace-api/index.rst b/Documentation/userspace-api/index.rst
index acd2cc2a538d..d29b020e5622 100644
--- a/Documentation/userspace-api/index.rst
+++ b/Documentation/userspace-api/index.rst
@@ -24,6 +24,7 @@  place where this information is gathered.
    ioctl/index
    iommu
    media/index
+   sysfs-platform_profile
 
 .. only::  subproject and html
 
diff --git a/Documentation/userspace-api/sysfs-platform_profile.rst b/Documentation/userspace-api/sysfs-platform_profile.rst
new file mode 100644
index 000000000000..56639d218003
--- /dev/null
+++ b/Documentation/userspace-api/sysfs-platform_profile.rst
@@ -0,0 +1,43 @@ 
+=====================================================================
+Platform Profile Selection (e.g. /sys/firmware/acpi/platform_profile)
+=====================================================================
+
+On modern systems the platform performance, temperature, fan and other
+hardware related characteristics are often dynamically configurable. The
+profile is often automatically adjusted to the load by some
+automatic mechanism (which may very well live outside the kernel).
+
+These auto platform adjustment mechanisms often can be configured with
+one of several platform profiles, with either a bias towards low power
+operation or towards performance.
+
+The purpose of the platform_profile attribute is to offer a generic sysfs
+API for selecting the platform profile of these automatic mechanisms.
+
+Note that this API is only for selecting the platform profile, it is
+NOT a goal of this API to allow monitoring the resulting performance
+characteristics. Monitoring performance is best done with device/vendor
+specific tools such as e.g. turbostat.
+
+Specifically when selecting a high performance profile the actual achieved
+performance may be limited by various factors such as: the heat generated
+by other components, room temperature, free air flow at the bottom of a
+laptop, etc. It is explicitly NOT a goal of this API to let userspace know
+about any sub-optimal conditions which are impeding reaching the requested
+performance level.
+
+Since numbers on their own cannot represent the multiple variables that a
+profile will adjust (power consumption, heat generation, etc) this API
+uses strings to describe the various profiles. To make sure that userspace
+gets a consistent experience the sysfs-platform_profile ABI document defines
+a fixed set of profile names. Drivers *must* map their internal profile
+representation onto this fixed set.
+
+If there is no good match when mapping then a new profile name may be
+added. Drivers which wish to introduce new profile names must:
+
+ 1. Explain why the existing profile names canot be used.
+ 2. Add the new profile name, along with a clear description of the
+    expected behaviour, to the sysfs-platform_profile ABI documentation.
+
+