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