| Mark Pearson | 8e0cbf3 | 2020-12-29 19:18:25 -0500 | [diff] [blame] | 1 | ===================================================================== |
| 2 | Platform Profile Selection (e.g. /sys/firmware/acpi/platform_profile) |
| 3 | ===================================================================== |
| 4 | |
| 5 | On modern systems the platform performance, temperature, fan and other |
| 6 | hardware related characteristics are often dynamically configurable. The |
| 7 | platform configuration is often automatically adjusted to the current |
| 8 | conditions by some automatic mechanism (which may very well live outside |
| 9 | the kernel). |
| 10 | |
| 11 | These auto platform adjustment mechanisms often can be configured with |
| 12 | one of several platform profiles, with either a bias towards low power |
| 13 | operation or towards performance. |
| 14 | |
| 15 | The purpose of the platform_profile attribute is to offer a generic sysfs |
| 16 | API for selecting the platform profile of these automatic mechanisms. |
| 17 | |
| 18 | Note that this API is only for selecting the platform profile, it is |
| 19 | NOT a goal of this API to allow monitoring the resulting performance |
| 20 | characteristics. Monitoring performance is best done with device/vendor |
| 21 | specific tools such as e.g. turbostat. |
| 22 | |
| 23 | Specifically when selecting a high performance profile the actual achieved |
| 24 | performance may be limited by various factors such as: the heat generated |
| 25 | by other components, room temperature, free air flow at the bottom of a |
| 26 | laptop, etc. It is explicitly NOT a goal of this API to let userspace know |
| 27 | about any sub-optimal conditions which are impeding reaching the requested |
| 28 | performance level. |
| 29 | |
| 30 | Since numbers on their own cannot represent the multiple variables that a |
| 31 | profile will adjust (power consumption, heat generation, etc) this API |
| 32 | uses strings to describe the various profiles. To make sure that userspace |
| 33 | gets a consistent experience the sysfs-platform_profile ABI document defines |
| 34 | a fixed set of profile names. Drivers *must* map their internal profile |
| 35 | representation onto this fixed set. |
| 36 | |
| 37 | If there is no good match when mapping then a new profile name may be |
| 38 | added. Drivers which wish to introduce new profile names must: |
| 39 | |
| 40 | 1. Explain why the existing profile names canot be used. |
| 41 | 2. Add the new profile name, along with a clear description of the |
| 42 | expected behaviour, to the sysfs-platform_profile ABI documentation. |