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@xxxxxxxxxx> Signed-off-by: Mark Pearson <markpearson@xxxxxxxxxx> Signed-off-by: Hans de Goede <hdegoede@xxxxxxxxxx> --- Changes in v2: - updated to rst format Changes in v3, v4 & v5: - version bump along with rest of patch series .../ABI/testing/sysfs-platform_profile.rst | 66 +++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 Documentation/ABI/testing/sysfs-platform_profile.rst diff --git a/Documentation/ABI/testing/sysfs-platform_profile.rst b/Documentation/ABI/testing/sysfs-platform_profile.rst new file mode 100644 index 000000000000..5f7b2a94409b --- /dev/null +++ b/Documentation/ABI/testing/sysfs-platform_profile.rst @@ -0,0 +1,66 @@ +======================================================================= + 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 this API 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 documentation. + +:What: /sys/firmware/acpi/platform_profile_choices +:Date: October 2020 +:Contact: Hans de Goede <hdegoede@xxxxxxxxxx> +: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@xxxxxxxxxx> +: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. -- 2.28.0
